# Transmettre des en-têtes personnalisés à Amazon Bedrock Runtime AgentCore
<a name="runtime-header-allowlist"></a>

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](#runtime-header-restrictions), y compris les signatures de webhook`X-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'`Authorization`en-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 :
+ [Le nom d'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.](#runtime-header-restrictions)
+ Les en-têtes commençant par 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'`Authorization`en-tête nécessite que le runtime de l'agent soit configuré avec un `customJWTAuthorizer` pour OAuth-based l'accès entrant.
+ 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 majuscules/majuscules et les doublons (par comparaison entre majuscules et minuscules) ne sont pas autorisés.

## En-têtes restreints
<a name="runtime-header-restrictions"></a>

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-token``x-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
<a name="create-agent-headers"></a>

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
<a name="deploy-agentcore-runtime"></a>

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.

**Example**  

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.

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_runtime`est 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écutant`agentcore status`.

## Étape 3 : Invoquez votre agent avec des en-têtes personnalisés
<a name="invoke-custom-headers"></a>

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.

**Example**  

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"
   ```

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](https://botocore.amazonaws.com/v1/documentation/api/latest/topics/events.html).

   ```
   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
<a name="pass-jwt-token"></a>

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.

**Example**  

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'`Authorization`en-tête des demandes entrantes est validé par rapport à votre fournisseur OIDC et transmis à votre code d'agent.

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](runtime-oauth.md) l'authentification sortante.