View a markdown version of this page

Transmettre des en-têtes personnalisés à Amazon Bedrock Runtime AgentCore - Base rocheuse de l'Amazonie 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

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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

Les en-têtes personnalisés vous permettent de transmettre des informations contextuelles de votre application directement au code de votre agent sans encombrer la charge utile de la demande principale. Vous pouvez transmettre tout en-tête HTTP valide qui ne figure pas dans la liste des en-têtes restreints, y compris les signatures de webhook telles que les clés d'APIX-Custom-Signature, le contexte de trace ou les identifiants de session. X-Api-Key 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 compatibilité descendante ». 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 des en-têtes dans une demande au code de votre agent à condition que les en-têtes répondent aux critères suivants :

  • Le nom de l'en-tête est un en-tête HTTP valide (caractères alphanumériques, traits d'union et traits de soulignement) et ne figure pas dans la liste des en-têtes restreints.

  • Les en-têtes commençant par N ne x-amz- sont pas autorisés (ils sont réservés à la signature AWS SIGv4).

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

  • L'Authorizationen-tête nécessite que l'environnement d'exécution de l'agent soit configuré avec un customJWTAuthorizer pour OAuth-based l'accès entrant.

  • La taille de la valeur de l'en-tête n'est pas supérieure à 4 Ko.

  • Jusqu'à 20 en-têtes peuvent être configurés par exécution.

  • Les noms d'en-tête ne font pas la distinction entre majuscules et minuscules et les doublons (par comparaison sans distinction majuscules/minuscules) ne sont pas autorisés.

En-têtes restreints

Pour garantir la sécurité et empêcher l'exposition 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, Pragma If-Unmodified-Since Last-Modified, Vary

Gestion des connexions

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

Contexte de la demande

Hôte User-Agent, référent, expéditeur

Portée/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, DPR Accept-CH-Lifetime, 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

Par, 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-token,x-amz-date,x-amz-content-sha256). Elles sont réservées à 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 vide, puis ajoutez un agent avec l'en-tête de demande Allowlist :

agentcore create --project-name MyHeaderProject --no-agent
cd MyHeaderProject
agentcore add agent \
  --name MyHeaderAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --request-header-allowlist X-Custom-Signature,X-Api-Key,X-Amzn-Bedrock-AgentCore-Runtime-Custom-UserId

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", "")
    if not isinstance(user_message, str) or not user_message.strip():
        return {"error": "Invalid input: 'prompt' must be a non-empty string"}
    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 autorisée des en-têtes de demande sur l'environnement d'exécution de votre agent afin que les en-têtes personnalisés soient transmis au code de votre agent au moment de l'invocation.

Exemple
AgentCore CLI

  1. La agentcore add agent commande de l'étape 1 stocke la liste d'autorisations dans la configuration d'exécution runtimes sousagentcore/agentcore.json.

    Déployez votre agent :

    agentcore deploy

    Notez l'ARN d'exécution de l'agent figurant sur la sortie. Vous en avez besoin si vous prévoyez d'invoquer à 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 été modifiés.

    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 invoquez 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 avec 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 les gestionnaires d'événements pour ajouter des en-têtes personnalisés à l'appel 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. Pour utiliser l'authentification JWT, exécutez la commande suivante au lieu de la agentcore add agent commande de l'étape 1 :

    agentcore add agent \
  --name MyHeaderAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --authorizer-type CUSTOM_JWT \
  --discovery-url "https://cognito-idp.us-east-1.amazonaws.com/user-pool-id/.well-known/openid-configuration" \
  --allowed-audience "your-client-id" \
  --allowed-clients "your-client-id" \
  --request-header-allowlist 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 transféré vers 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 Authentification et autorisation avec Inbound Auth et Outbound Auth.