View a markdown version of this page

Transmettre des en-têtes personnalisés à Amazon Bedrock Runtime AgentCore - Amazon Bedrock AgentCore
En-têtes restreintsÉtape 1 : Créez votre agentÉtape 2 : configurer et déployer votre agent avec des en-têtes personnalisésÉtape 3 : Invoquez votre agent avec des en-têtes personnalisésÉtape 4 : (Facultatif) Configurer l'authentification JWT entrante

Transmettre des en-têtes personnalisés à Amazon Bedrock Runtime AgentCore

Les en-têtes personnalisés vous permettent de transmettre les informations contextuelles de votre application directement au code de votre agent sans encombrer la charge utile de la demande principale. Vous pouvez transmettre n'importe quel en-tête HTTP valide qui ne figure pas dans la liste des en-têtes restreints, y compris les signatures de webhookX-Custom-Signature, les clés d'API telles que X-Api-Key le contexte de trace ou les identifiants de session. Vous pouvez également transmettre l'Authorizationen-tête pour l' JWT-based authentification lorsque votre agent est configuré avec un autorisateur JWT personnalisé. Les en-têtes préfixés par « X-Amzn-Bedrock-AgentCore-Runtime-Custom- continuent d'être pris en charge pour des raisons de rétrocompatibilité ». Jusqu'à 20 en-têtes peuvent être configurés par exécution, et chaque valeur d'en-tête est limitée à 4 Ko.

Amazon Bedrock AgentCore Runtime vous permet de transmettre les en-têtes d'une demande au code de votre agent, à condition que les en-têtes répondent aux critères suivants :

En-têtes restreints

Pour garantir la sécurité et empêcher la divulgation d'informations sensibles, les en-têtes suivants sont restreints et ne peuvent pas être configurés pour la propagation :

Catégorie En-têtes

Authentification et autorisation

Proxy-Authorization, WWW-Authenticate

Négociation de contenu

Acceptez Accept-Charset, Accept-Encoding Accept-Language, Content-Type, Content-Length, Content-Encoding, Content-Language, Content-Location, Content-Range

Mise en cache

Cache-Control, eTag, Expire,, If-Match,, If-Modified-Since, If-None-Match, If-Range If-Unmodified-Since, Pragma Last-Modified, Vary

Gestion des connexions

Connexion, Keep-Alive Proxy-Connection, Mise à niveau

Contexte de la demande

Hôte, Référent User-Agent, Expéditeur

Gamme/Transfert

Range Accept-Ranges, Transfer-Encoding, TE, remorque

Informations sur le serveur

Serveur, date, emplacement, Retry-After

Cookies

Set-Cookie, Biscuit

Sécurité

Content-Security-Policy, Content-Security-Policy-Report-Only, Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy, Permissions-Policy, Cross-Origin-Embedder-Policy, Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy

CORS

Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, Access-Control-Allow-Credentials Access-Control-Expose-Headers, Access-Control-Max-Age, Access-Control-Request-Method, Access-Control-Request-Headers, Origine

Conseils aux clients

Accept-CH Accept-CH-Lifetime, DPR, largeur, liaison descendante Viewport-Width, ECT, RTT, Save-Data

Expérimental/Proposé

Clear-Site-Data, Feature-Policy, Expect-CT, Public-Key-Pins, Public-Key-Pins-Report-Only

Proxy

Via, Transféré X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto, X-Real-IP, X-Requested-With, X-CSRF-Token

Usurpation d'adresse IP/manipulation d'URL

True-Client-IP, X-Client-IP, X-Cluster-Client-IP, X-Originating-IP, X-Source-IP, X-Original-URL, X-Original-Host, X-Rewrite-URL

CDN/Proxy

CF-Ray, CF-Connecting-IP, X-Amz-Cf-Id, X-Cache, X-Served-By

HTTP/2 Pseudo-en-têtes

:method, :path, :scheme, :authority, :status

Serveur Push

Lien

WebSocket

Sec-WebSocket-Key, Sec-WebSocket-Accept, Sec-WebSocket-Version, Sec-WebSocket-Protocol, Sec-WebSocket-Extensions

Outre les en-têtes restreints répertoriés ci-dessus :

  • Tous les en-têtes commençant par x-amz- sont restreints (par exemple, x-amz-security-tokenx-amz-date,x-amz-content-sha256). Ils sont réservés à la signature des AWS demandes.

  • Tous les en-têtes commençant par x-amzn- sont restreints, à l'exception des en-têtes préfixés par. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

Étape 1 : Créez votre agent

Créez un AgentCore projet à l'aide de la AgentCore CLI :

agentcore create --name MyHeaderAgent
cd MyHeaderAgent

Mettez à jour le fichier de point d'entrée de votre agent pour accéder aux en-têtes personnalisés depuis le contexte de la demande :

import json
from bedrock_agentcore import BedrockAgentCoreApp, RequestContext
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent()

@app.entrypoint
def agent_invocation(payload, context: RequestContext):
    """Handler for agent invocation"""
    user_message = payload.get(
        "prompt", "No prompt found in input, please guide customer to create a json payload with prompt key"
    )
    app.logger.info("invoking agent with user message: %s", payload)
    response = agent(user_message)

    # access request headers here
    request_headers = context.request_headers
    app.logger.info("Headers: %s", json.dumps(request_headers))
    return response

app.run()

Étape 2 : configurer et déployer votre agent avec des en-têtes personnalisés

Configurez la liste d'autorisation des en-têtes de demande sur le runtime de votre agent afin que les en-têtes personnalisés soient transférés vers le code de votre agent au moment de l'appel.

Exemple
AgentCore CLI

  1. Ajoutez le requestHeaderAllowlist champ à la configuration de votre agent dans agentcore/agentcore.json :

    {
  "agents": [
    {
      "name": "MyHeaderAgent",
      "requestHeaderAllowlist": [
        "X-Custom-Signature",
        "X-Api-Key",
        "X-Amzn-Bedrock-AgentCore-Runtime-Custom-UserId"
      ]
    }
  ]
}

    Déployez votre agent :

    agentcore deploy

    Notez l'ARN d'exécution de l'agent indiqué dans la sortie. Vous en avez besoin si vous envisagez d'appeler à l'aide du AWS SDK.

AWS SDK

  1. Après avoir déployé votre agent, mettez à jour la configuration d'exécution à l'aide du AWS SDK :

    import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

client.update_agent_runtime(
    agentRuntimeId='your-runtime-id',
    roleArn='arn:aws:iam::123456789012:role/YourAgentRole',
    agentRuntimeArtifact={'containerConfiguration': {'containerUri': 'your-container-uri'}},
    networkConfiguration={'networkMode': 'PUBLIC'},
    requestHeaderConfiguration={
        'requestHeaderAllowlist': [
            'X-Custom-Signature',
            'X-Api-Key'
        ]
    }
)
    Note

    update_agent_runtimeest une opération PUT complète. Vous devez inclure tous les champs obligatoires (roleArn,agentRuntimeArtifact,networkConfiguration) même s'ils n'ont pas changé.

    Vous pouvez trouver votre identifiant d'exécution en exécutantagentcore status.

Étape 3 : Invoquez votre agent avec des en-têtes personnalisés

Transmettez des en-têtes personnalisés lorsque vous appelez votre agent afin que votre code d'agent puisse y accéder via le contexte de la demande.

Exemple
AgentCore CLI

  1. Utilisez le -H drapeau pour transmettre des en-têtes personnalisés contenant agentcore invoke :

    agentcore invoke "Tell me a joke" \
  -H "X-Custom-Signature: sha256=abc123def456"

    Vous pouvez transmettre plusieurs en-têtes en répétant le -H drapeau :

    agentcore invoke "Tell me a joke" \
  -H "X-Custom-Signature: sha256=abc123def456" \
  -H "X-Api-Key: my-api-key" \
  -H "X-Amzn-Bedrock-AgentCore-Runtime-Custom-UserId: user-123"
AWS SDK

  1. Utilisez boto3 avec des gestionnaires d'événements pour ajouter des en-têtes personnalisés à l'invocation de votre agent. Pour plus de détails sur les événements botocore, consultez la documentation sur les événements botocore.

    import json
import boto3

agent_arn = 'YOUR_AGENT_ARN_HERE'
prompt = "Tell me a joke"

agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2')
event_system = agent_core_client.meta.events

EVENT_NAME = 'before-sign.bedrock-agentcore.InvokeAgentRuntime'
CUSTOM_HEADER_NAME = 'X-Custom-Signature'
CUSTOM_HEADER_VALUE = 'sha256=abc123def456'

def add_custom_runtime_header(request, **kwargs):
    request.headers.add_header(CUSTOM_HEADER_NAME, CUSTOM_HEADER_VALUE)

handler = event_system.register_first(EVENT_NAME, add_custom_runtime_header)

payload = json.dumps({"prompt": prompt}).encode()
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    payload=payload
)

event_system.unregister(EVENT_NAME, handler)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode('utf-8'))
print(json.loads(''.join(content)))

Étape 4 : (Facultatif) Configurer l'authentification JWT entrante

Pour transmettre le jeton JWT utilisé pour l'accès OAuth-based entrant à votre agent, configurez authorizerType et authorizerConfiguration dans la configuration de votre agent.

Exemple
AgentCore CLI

  1. Ajoutez la configuration de l'autorisateur à votre agent dans agentcore/agentcore.json :

    {
  "agents": [
    {
      "name": "MyHeaderAgent",
      "authorizerType": "CUSTOM_JWT",
      "authorizerConfiguration": {
        "customJwtAuthorizer": {
          "discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/user-pool-id/.well-known/openid-configuration",
          "allowedAudience": ["your-client-id"],
          "allowedClients": ["your-client-id"]
        }
      },
      "requestHeaderAllowlist": [
        "Authorization"
      ]
    }
  ]
}

    Déployez pour appliquer la configuration :

    agentcore deploy

    Avec cette configuration, l'Authorizationen-tête des demandes entrantes est validé par rapport à votre fournisseur OIDC et transmis à votre code d'agent.

AWS SDK

  1. Pour plus d'informations sur la configuration d'un agent avec un accès entrant OAuth à l'aide du AWS SDK, consultez Authentifier et autoriser avec l'authentification entrante et l'authentification sortante.