# Passa intestazioni personalizzate ad Amazon AgentCore Bedrock Runtime
<a name="runtime-header-allowlist"></a>

Le intestazioni personalizzate consentono di passare le informazioni contestuali dall'applicazione direttamente al codice dell'agente senza ingombrare il payload della richiesta principale. Puoi passare qualsiasi intestazione HTTP valida che non sia presente nell'elenco delle [intestazioni con restrizioni, incluse le firme dei webhook come le chiavi API`X-Custom-Signature`, il contesto di traccia o gli identificatori](#runtime-header-restrictions) di sessione. `X-Api-Key` Puoi anche passare l'`Authorization`intestazione per l' JWT-based autenticazione quando il tuo agente è configurato con un autorizzatore JWT personalizzato. Le intestazioni con prefisso da `X-Amzn-Bedrock-AgentCore-Runtime-Custom-` continuano a essere supportate per la compatibilità con le versioni precedenti. È possibile configurare fino a 20 intestazioni per runtime e ogni valore di intestazione è limitato a 4 KB.

Amazon Bedrock AgentCore Runtime ti consente di passare le intestazioni in una richiesta al tuo codice agente, a condizione che le intestazioni soddisfino i seguenti criteri:
+ [Il nome dell'intestazione è un'intestazione HTTP valida (caratteri alfanumerici, trattini e caratteri di sottolineatura) e non è presente nell'elenco delle intestazioni con restrizioni.](#runtime-header-restrictions)
+ Le intestazioni che iniziano con non `x-amz-` sono consentite (sono riservate alla firma di SigV4). AWS 
+ Le intestazioni che iniziano con non `x-amzn-` sono consentite, ad eccezione delle intestazioni con il prefisso. `X-Amzn-Bedrock-AgentCore-Runtime-Custom-`
+ L'`Authorization`intestazione richiede che il runtime dell'agente sia configurato con un `customJWTAuthorizer` per l'accesso in entrata. OAuth-based 
+ Il valore dell'intestazione non ha una dimensione superiore a 4 KB.
+ È possibile configurare fino a 20 intestazioni per runtime.
+ I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole e i duplicati (per confronto senza distinzione tra maiuscole e minuscole) non sono consentiti.

## Intestazioni con restrizioni
<a name="runtime-header-restrictions"></a>

Per mantenere la sicurezza e prevenire l'esposizione di informazioni sensibili, le seguenti intestazioni sono limitate e non possono essere configurate per la propagazione:


| Categoria | Intestazioni  | 
| --- | --- | 
| Autenticazione e autorizzazione | Proxy-Authorization, WWW-Authenticate | 
| Negoziazione di contenuto | Accetta Accept-Charset, Accept-Encoding, Accept-Language, Content-Type, Content-Length, Content-Encoding, Content-Language, Content-Location, Content-Range | 
| Caching | Cache-Control, eTag, Scade,,,, If-Match,, If-Modified-Since, If-None-Match If-Range, If-Unmodified-Since Pragma Last-Modified, Vary | 
| Gestione delle connessioni | Connessione,,, Aggiornamento Keep-Alive Proxy-Connection | 
| Contesto della richiesta | Host User-Agent, Referer, Da | 
| Intervallo/ Trasferimento | Intervallo Accept-Ranges, Transfer-Encoding, TE, rimorchio | 
| Informazioni sul server | Server, data, ubicazione, Retry-After | 
| Cookie | Set-Cookie, Cookie | 
| Sicurezza | 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 | 
| NUCLEO | 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 | 
| Suggerimenti per i clienti | Accept-CH Accept-CH-Lifetime, DPR, larghezza, downlink Viewport-Width, ECT, RTT, Save-Data | 
| Sperimentale/Proposto | Clear-Site-Data, Feature-Policy, Expect-CT, Public-Key-Pins, Public-Key-Pins-Report-Only | 
| Proxy | Tramite, inoltrato, X-Forwarded-For, X-Forwarded-Host,, X-Forwarded-Proto, X-Real-IP X-Requested-With X-CSRF-Token | 
| Spoofing dell'IP/Manipolazione degli 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 intestazioni | :metodo, :percorso, :schema, :autorità, :status | 
| Spinta dal server | Link | 
| WebSocket | Sec-WebSocket-Key, Sec-WebSocket-Accept, Sec-WebSocket-Version, Sec-WebSocket-Protocol, Sec-WebSocket-Extensions | 

Oltre alle intestazioni con restrizioni elencate sopra:
+ Tutte le intestazioni che iniziano con `x-amz-` sono limitate (ad esempio, `x-amz-security-token``x-amz-date`,`x-amz-content-sha256`). Queste sono riservate alla firma delle AWS richieste.
+ Tutte le intestazioni che iniziano con `x-amzn-` sono limitate, ad eccezione delle intestazioni con prefisso. `X-Amzn-Bedrock-AgentCore-Runtime-Custom-`

## Fase 1: Crea il tuo agente
<a name="create-agent-headers"></a>

Crea un AgentCore progetto utilizzando la AgentCore CLI:

```
agentcore create --name MyHeaderAgent
cd MyHeaderAgent
```

Aggiorna il file entrypoint del tuo agente per accedere alle intestazioni personalizzate dal contesto della richiesta:

```
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()
```

## Passaggio 2: configura e distribuisci il tuo agente con intestazioni personalizzate
<a name="deploy-agentcore-runtime"></a>

Configura l'elenco degli indirizzi consentiti delle intestazioni di richiesta nel runtime dell'agente in modo che le intestazioni personalizzate vengano inoltrate al codice dell'agente al momento della chiamata.

**Example**  

1. Aggiungi il campo alla configurazione del tuo agente in`requestHeaderAllowlist`: `agentcore/agentcore.json`

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

   Implementa il tuo agente:

   ```
   agentcore deploy
   ```

   Annotate l'ARN del runtime dell'agente dall'output. Ne hai bisogno se prevedi di richiamare utilizzando l' AWS SDK.

1. Dopo aver distribuito l'agente, aggiorna la configurazione di runtime utilizzando l'SDK: AWS 

   ```
   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'
           ]
       }
   )
   ```
**Nota**  
 `update_agent_runtime`è un'operazione PUT completa. È necessario includere tutti i campi obbligatori (`roleArn`,`agentRuntimeArtifact`,`networkConfiguration`) anche se non sono stati modificati.

   Puoi trovare il tuo ID di runtime eseguendo`agentcore status`.

## Passaggio 3: richiama il tuo agente con intestazioni personalizzate
<a name="invoke-custom-headers"></a>

Passa intestazioni personalizzate quando richiami il tuo agente in modo che il codice dell'agente possa accedervi tramite il contesto della richiesta.

**Example**  

1. Usa il `-H` flag per passare intestazioni personalizzate con: `agentcore invoke`

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

   Puoi passare più intestazioni ripetendo il flag: `-H`

   ```
   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. Usa boto3 con i gestori di eventi per aggiungere intestazioni personalizzate alla chiamata dell'agente. [Per maggiori dettagli sugli eventi botocore, consulta la documentazione sugli eventi 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)))
   ```

## Fase 4: (Facoltativo) Configurazione dell'autenticazione JWT in entrata
<a name="pass-jwt-token"></a>

Per passare il token JWT utilizzato per l'accesso OAuth-based in entrata al tuo agente, configura `authorizerType` e `authorizerConfiguration` nella configurazione dell'agente.

**Example**  

1. Aggiungi la configurazione dell'autorizzatore al tuo agente in: `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"
         ]
       }
     ]
   }
   ```

   Esegui la distribuzione per applicare la configurazione:

   ```
   agentcore deploy
   ```

   Con questa configurazione, l'`Authorization`intestazione delle richieste in arrivo viene convalidata rispetto al provider OIDC e inoltrata al codice dell'agente.

1. [Per informazioni sulla configurazione di un agente con accesso in entrata OAuth tramite l' AWS SDK, consulta Autenticare e autorizzare con Inbound Auth e Outbound Auth.](runtime-oauth.md)