View a markdown version of this page

Pase encabezados personalizados a Amazon Bedrock Runtime AgentCore - Amazon Bedrock AgentCore
Encabezados restringidosPaso 1: Crea tu agentePaso 2: Configura e implementa tu agente con encabezados personalizadosPaso 3: invoca a tu agente con encabezados personalizadosPaso 4: (opcional) Configurar la autenticación JWT entrante

Pase encabezados personalizados a Amazon Bedrock Runtime AgentCore

Los encabezados personalizados te permiten pasar la información contextual de tu aplicación directamente al código de tu agente sin sobrecargar la carga útil de la solicitud principal. Puedes pasar cualquier encabezado HTTP válido que no esté en la lista de encabezados restringidos, incluidas las firmas de webhook (por ejemplo), las claves de API (por ejemplo)X-Custom-Signature, el contexto de rastreo o los identificadores de X-Api-Key sesión. También puedes pasar el Authorization encabezado para la JWT-based autenticación cuando tu agente esté configurado con un autorizador JWT personalizado. Se X-Amzn-Bedrock-AgentCore-Runtime-Custom- siguen admitiendo los encabezados con el prefijo por motivos de compatibilidad con versiones anteriores. Se pueden configurar hasta 20 encabezados por tiempo de ejecución y cada valor de encabezado está limitado a 4 KB.

Amazon Bedrock AgentCore Runtime le permite pasar los encabezados de una solicitud a su código de agente siempre que los encabezados cumplan los siguientes criterios:

  • El nombre del encabezado es un encabezado HTTP válido (caracteres alfanuméricos, guiones y guiones bajos) y no figura en la lista de encabezados restringidos.

  • No se permiten encabezados que comiencen por (x-amz-están reservados para la firma SigV4). AWS

  • No x-amzn- se permiten encabezados que comiencen por, excepto los encabezados con el prefijo. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

  • El Authorization encabezado requiere que el tiempo de ejecución del agente esté configurado con un customJWTAuthorizer para OAuth-based el acceso entrante.

  • El tamaño del encabezado no supera los 4 KB.

  • Se pueden configurar hasta 20 encabezados por tiempo de ejecución.

  • Los nombres de los encabezados no distinguen mayúsculas de minúsculas y no se permiten duplicados (comparándolos con mayúsculas y minúsculas).

Encabezados restringidos

Para mantener la seguridad y evitar la exposición de información confidencial, los siguientes encabezados están restringidos y no se pueden configurar para su propagación:

Categoría Encabezados

Autenticación y autorización

Proxy-Authorization, WWW-Authenticate

Negociación de contenido

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

Almacenamiento en caché

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

Administración de conexiones

Conexión Keep-Alive, actualización Proxy-Connection

Contexto de la solicitud

Anfitrión User-Agent, Referente, Desde

Alcance/transferencia

Alcance Accept-Ranges Transfer-Encoding, TE, remolque

Información del servidor

Servidor, fecha, ubicación, Retry-After

Cookies

Set-Cookie, Cookie

Seguridad

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

CORALES

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

Consejos para el cliente

Accept-CH Accept-CH-Lifetime, DPR, ancho, enlace descendente Viewport-Width, ECT, RTT, Save-Data

Experimental/Propuesto

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

Proxy

Vía, Reenviado X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto, X-Real-IP, X-Requested-With, X-CSRF-Token

Falsificación de IP/manipulación 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 Pseudoencabezados

:método, :ruta, :esquema, :autoridad, :estado

Servidor Push

Link

WebSocket

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

Además de los encabezados restringidos enumerados anteriormente:

  • Todos los encabezados que comiencen por x-amz- están restringidos (por ejemplo,, x-amz-security-tokenx-amz-date,x-amz-content-sha256). Están reservados para la firma de AWS solicitudes.

  • Todos los encabezados que comiencen por x-amzn- están restringidos, excepto los encabezados con el prefijo. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

Paso 1: Crea tu agente

Cree un AgentCore proyecto mediante la AgentCore CLI:

agentcore create --name MyHeaderAgent
cd MyHeaderAgent

Actualice el archivo de puntos de entrada de su agente para acceder a los encabezados personalizados desde el contexto de la solicitud:

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

Paso 2: Configura e implementa tu agente con encabezados personalizados

Configure la lista de encabezados de solicitud permitidos en el entorno de ejecución de su agente para que los encabezados personalizados se envíen al código de su agente en el momento de la invocación.

ejemplo
AgentCore CLI

  1. Añada el requestHeaderAllowlist campo a la configuración de su agente en: agentcore/agentcore.json

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

    Despliegue su agente:

    agentcore deploy

    Anote el ARN del tiempo de ejecución del agente en el resultado. Lo necesitará si planea invocarlo mediante el AWS SDK.

AWS SDK

  1. Tras implementar el agente, actualice la configuración del tiempo de ejecución mediante el 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_runtimees una operación PUT completa. Debe incluir todos los campos obligatorios (roleArnagentRuntimeArtifact,,networkConfiguration) aunque no hayan cambiado.

    Para encontrar tu ID de tiempo de ejecución, ejecutaagentcore status.

Paso 3: invoca a tu agente con encabezados personalizados

Pase encabezados personalizados al invocar a su agente para que su código de agente pueda acceder a ellos a través del contexto de la solicitud.

ejemplo
AgentCore CLI

  1. Usa la -H marca para pasar encabezados personalizados con: agentcore invoke

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

    Puedes pasar varios encabezados repitiendo la -H marca:

    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 controladores de eventos para añadir encabezados personalizados a la invocación de tu agente. Para obtener más información sobre los eventos de botocore, consulte la documentación de los 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)))

Paso 4: (opcional) Configurar la autenticación JWT entrante

Para transferir el token JWT utilizado para el acceso OAuth-based entrante a su agente, configure authorizerType y authorizerConfiguration en la configuración de su agente.

ejemplo
AgentCore CLI

  1. Añada la configuración del autorizador a su agente en: 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"
      ]
    }
  ]
}

    Implemente para aplicar la configuración:

    agentcore deploy

    Con esta configuración, el Authorization encabezado de las solicitudes entrantes se valida con su proveedor de OIDC y se reenvía a su código de agente.

AWS SDK

  1. Para obtener información sobre cómo configurar un agente con acceso entrante de OAuth mediante el AWS SDK, consulte Autenticar y autorizar con autenticación entrante y autenticación saliente.