View a markdown version of this page

Passa intestazioni personalizzate ad Amazon AgentCore Bedrock Runtime - Fondamento Amazon AgentCore
Intestazioni soggette a restrizioniFase 1: Crea il tuo agentePassaggio 2: configura e implementa il tuo agente con intestazioni personalizzatePassaggio 3: richiama il tuo agente con intestazioni personalizzateFase 4: (Facoltativo) Configurare l'autenticazione JWT in entrata

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Passa intestazioni personalizzate ad Amazon AgentCore Bedrock Runtime

Le intestazioni personalizzate ti 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 soggette a restrizioni, comprese le firme dei webhook, le chiavi APIX-Custom-Signature, il contesto di traccia o gli identificatori di sessione. X-Api-Key Puoi anche passare l'Authorizationintestazione per l' JWT-based autenticazione quando il tuo agente è configurato con un autorizzatore JWT personalizzato. Le intestazioni precedute 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 di 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 soggette a restrizioni. Intestazioni soggette a restrizioni

  • Le intestazioni che iniziano con non x-amz- sono consentite (sono riservate alla firma Sigv4). AWS

  • Le intestazioni che iniziano con non x-amzn- sono consentite, ad eccezione delle intestazioni precedute da. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

  • L'Authorizationintestazione richiede che il runtime dell'agente sia configurato con un customJWTAuthorizer per l'accesso in entrata. OAuth-based

  • Il valore dell'intestazione non è 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 (mediante confronto senza distinzione tra maiuscole e minuscole) non sono consentiti.

Intestazioni soggette a restrizioni

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

Gamma, Accept-Ranges, TE Transfer-Encoding, rimorchio

Informazioni sul server

Server, data, posizione, Retry-After

Cookie

Set-Cookie, Biscotto

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

CORDE

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/Proposta

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

Proxy

Via, Inoltrato, X-Forwarded-For,, X-Forwarded-Host, X-Forwarded-Proto, X-Real-IP X-Requested-With X-CSRF-Token

Spoofing 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

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

Push del server

Link

WebSocket

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

Oltre alle intestazioni limitate elencate sopra:

  • Tutte le intestazioni che iniziano con x-amz- sono limitate (ad esempio, x-amz-security-tokenx-amz-date,x-amz-content-sha256). Sono riservate alla firma delle AWS richieste.

  • Tutte le intestazioni che iniziano con x-amzn- sono limitate, ad eccezione delle intestazioni precedute da. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

Fase 1: Crea il tuo agente

Crea un AgentCore progetto vuoto, quindi aggiungi un agente con l'intestazione della richiesta 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

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", "")
    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()

Passaggio 2: configura e implementa il tuo agente con intestazioni personalizzate

Configura l'header allowlist della richiesta nel runtime dell'agente in modo che le intestazioni personalizzate vengano inoltrate al codice dell'agente al momento della chiamata.

Esempio
AgentCore CLI

  1. Il agentcore add agent comando nel passaggio 1 memorizza la lista consentita nella configurazione di runtime in. runtimes agentcore/agentcore.json

    Implementa il tuo agente:

    agentcore deploy

    Annota l'ARN di runtime dell'agente dall'output. Ne hai bisogno se intendi richiamarlo utilizzando l' AWS SDK.

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 eseguendoagentcore status.

Passaggio 3: richiama il tuo agente con intestazioni personalizzate

Passate le intestazioni personalizzate quando invocate il vostro agente in modo che il codice agente possa accedervi tramite il contesto della richiesta.

Esempio
AgentCore CLI

  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"
AWS SDK

  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) Configurare l'autenticazione JWT in entrata

Per passare il token JWT utilizzato per l'accesso OAuth-based in entrata all'agente, configura authorizerType e authorizerConfiguration inserisci la configurazione dell'agente.

Esempio
AgentCore CLI

  1. Per utilizzare l'autenticazione JWT, esegui il comando seguente anziché il agentcore add agent comando nel passaggio 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

    Implementa per applicare la configurazione:

    agentcore deploy

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

AWS SDK

  1. Per informazioni sulla configurazione di un agente con accesso in entrata OAuth utilizzando l' AWS SDK, vedi Autenticazione e autorizzazione con autenticazione in entrata e autenticazione in uscita. Autentica e autorizza con Inbound Auth e Outbound Auth