View a markdown version of this page

Passa intestazioni personalizzate ad Amazon AgentCore Bedrock Runtime - Amazon Bedrock AgentCore
Intestazioni con restrizioniFase 1: Crea il tuo agentePassaggio 2: configura e distribuisci il tuo agente con intestazioni personalizzatePassaggio 3: richiama il tuo agente con intestazioni personalizzateFase 4: (Facoltativo) Configurazione dell'autenticazione JWT in entrata

Passa intestazioni personalizzate ad Amazon AgentCore Bedrock Runtime

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 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 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:

Intestazioni con 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

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-tokenx-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

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

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.

Esempio
AgentCore CLI

  1. Aggiungi il campo alla configurazione del tuo agente inrequestHeaderAllowlist: 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.

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

Passa intestazioni personalizzate quando richiami il tuo agente in modo che il codice dell'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.

    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

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

Esempio
AgentCore CLI

  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'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 tramite l' AWS SDK, consulta Autenticare e autorizzare con Inbound Auth e Outbound Auth.