View a markdown version of this page

Passe cabeçalhos personalizados para o Amazon Bedrock AgentCore Runtime - Amazon Bedrock AgentCore
Cabeçalhos restritosEtapa 1: Crie seu agenteEtapa 2: configurar e implantar seu agente com cabeçalhos personalizadosEtapa 3: invocar seu agente com cabeçalhos personalizadosEtapa 4: (opcional) configurar a autenticação JWT de entrada

Passe cabeçalhos personalizados para o Amazon Bedrock AgentCore Runtime

Os cabeçalhos personalizados permitem que você passe informações contextuais do seu aplicativo diretamente para o código do agente sem sobrecarregar a carga útil da solicitação principal. Você pode passar qualquer cabeçalho HTTP válido que não esteja na lista de cabeçalhos restritos, incluindo assinaturas de webhookX-Custom-Signature, como chaves de APIX-Api-Key, como contexto de rastreamento ou identificadores de sessão. Você também pode passar o Authorization cabeçalho para JWT-based autenticação quando seu agente estiver configurado com um autorizador JWT personalizado. Os cabeçalhos prefixados com X-Amzn-Bedrock-AgentCore-Runtime-Custom- continuam sendo suportados para compatibilidade com versões anteriores. Até 20 cabeçalhos podem ser configurados por tempo de execução, e cada valor de cabeçalho é limitado a 4 KB.

O Amazon Bedrock AgentCore Runtime permite que você passe cabeçalhos em uma solicitação para seu código de agente, desde que os cabeçalhos atendam aos seguintes critérios:

  • O nome do cabeçalho é um cabeçalho HTTP válido (caracteres alfanuméricos, hífens e sublinhados) e não está na lista de cabeçalhos restritos.

  • Cabeçalhos que começam com não x-amz- são permitidos (eles são reservados para AWS assinatura SigV4).

  • Cabeçalhos que começam com não x-amzn- são permitidos, exceto cabeçalhos prefixados com. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

  • O Authorization cabeçalho exige que o tempo de execução do agente seja configurado com um customJWTAuthorizer para acesso de OAuth-based entrada.

  • O valor do cabeçalho não é maior que 4 KB de tamanho.

  • Até 20 cabeçalhos podem ser configurados por tempo de execução.

  • Os nomes dos cabeçalhos não diferenciam maiúsculas de minúsculas e duplicatas (por comparação sem distinção entre maiúsculas e minúsculas) não são permitidas.

Cabeçalhos restritos

Para manter a segurança e evitar a exposição de informações confidenciais, os cabeçalhos a seguir são restritos e não podem ser configurados para propagação:

Categoria Cabeçalhos

Autenticação e autorização

Proxy-Authorization, WWW-Authenticate

Negociação de conteúdo

Aceite Accept-Charset, Accept-Encoding, Accept-Language,, Content-Type, Content-Length, Content-Encoding, Content-Language, Content-Location, Content-Range

Armazenamento em cache

Cache-Control, ETag, Expira,,, If-Match,, If-Modified-Since, If-None-Match If-Range, If-Unmodified-Since Pragma Last-Modified, Vary

Gerenciamento de conexões

Conexão Keep-Alive, Proxy-Connection,, Atualização

Contexto da solicitação

Anfitrião User-Agent, Referenciador, De

Alcance/Transferência

Alcance Accept-Ranges, Transfer-Encoding, TE, Trailer

Informações do servidor

Servidor, data, localização, Retry-After

Cookies

Set-Cookie, Biscoito

Segurança

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

NÚCLEOS

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, Origem

Dicas do cliente

Accept-CH Accept-CH-Lifetime, DPR, largura, downlink Viewport-Width, ECT, RTT, Save-Data

Experimental/Proposta

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

aplicativo web

Por meio de, Encaminhado, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto,, X-Real-IP, X-Requested-With X-CSRF-Token

Falsificação de IP/Manipulação de 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-cabeçalhos

:método, :caminho, :esquema, :autoridade, :status

Push do servidor

Link

WebSocket

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

Além dos cabeçalhos restritos listados acima:

  • Todos os cabeçalhos que começam com x-amz- são restritos (por exemplo,x-amz-security-token,x-amz-date,x-amz-content-sha256). Eles são reservados para assinatura de AWS solicitações.

  • Todos os cabeçalhos que começam com x-amzn- são restritos, exceto os cabeçalhos prefixados com. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

Etapa 1: Crie seu agente

Crie um AgentCore projeto usando a AgentCore CLI:

agentcore create --name MyHeaderAgent
cd MyHeaderAgent

Atualize o arquivo de ponto de entrada do seu agente para acessar os cabeçalhos personalizados a partir do contexto da solicitação:

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

Etapa 2: configurar e implantar seu agente com cabeçalhos personalizados

Configure a lista de permissões do cabeçalho da solicitação no tempo de execução do agente para que os cabeçalhos personalizados sejam encaminhados para o código do agente no momento da invocação.

exemplo
AgentCore CLI

  1. Adicione o requestHeaderAllowlist campo à configuração do seu agente emagentcore/agentcore.json:

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

    Implante seu agente:

    agentcore deploy

    Observe o ARN do tempo de execução do agente na saída. Você precisa dele se planeja invocar usando o AWS SDK.

AWS SDK

  1. Depois de implantar seu agente, atualize a configuração do tempo de execução usando o 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'
        ]
    }
)
    nota

    update_agent_runtimeé uma operação PUT completa. Você deve incluir todos os campos obrigatórios (roleArn,agentRuntimeArtifact,networkConfiguration) mesmo que eles não tenham sido alterados.

    Você pode encontrar seu ID de tempo de execução executandoagentcore status.

Etapa 3: invocar seu agente com cabeçalhos personalizados

Passe cabeçalhos personalizados ao invocar seu agente para que seu código de agente possa acessá-los por meio do contexto da solicitação.

exemplo
AgentCore CLI

  1. Use a -H bandeira para passar cabeçalhos personalizados comagentcore invoke:

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

    Você pode passar vários cabeçalhos repetindo a -H bandeira:

    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. Use o boto3 com manipuladores de eventos para adicionar cabeçalhos personalizados à invocação do seu agente. Para obter mais detalhes sobre eventos de botocore, consulte a documentação de eventos de 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)))

Etapa 4: (opcional) configurar a autenticação JWT de entrada

Para passar o token JWT usado para acesso de OAuth-based entrada ao seu agente, configure authorizerType e authorizerConfiguration na configuração do seu agente.

exemplo
AgentCore CLI

  1. Adicione a configuração do autorizador ao seu agente em: 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"
      ]
    }
  ]
}

    Implante para aplicar a configuração:

    agentcore deploy

    Com essa configuração, o Authorization cabeçalho das solicitações recebidas é validado em relação ao seu provedor OIDC e encaminhado para o código do seu agente.

AWS SDK

  1. Para obter informações sobre como configurar um agente com acesso de entrada OAuth usando o AWS SDK, consulte Autenticar e autorizar com Autenticação de Entrada e Autenticação de Saída.