View a markdown version of this page

Pase encabezados personalizados a Amazon Bedrock Runtime AgentCore - Base amazónica AgentCore
Encabezados restringidosPaso 1: Crea tu agentePaso 2: Configure e implemente su agente con encabezados personalizadosPaso 3: Invoca a tu agente con encabezados personalizadosPaso 4: (opcional) Configurar la autenticación JWT entrante

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

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 saturar la carga útil principal de la solicitud. Puedes pasar cualquier encabezado HTTP válido que no esté en la lista de encabezados restringidos, incluidas las firmas de webhooks, las claves de APIX-Custom-Signature, el contexto de seguimiento o los identificadores de X-Api-Key sesión. También puedes pasar el Authorization encabezado para la JWT-based autenticación si tu agente está configurado con un autorizador de JWT personalizado. Se X-Amzn-Bedrock-AgentCore-Runtime-Custom- siguen admitiendo los encabezados con el prefijo «con» 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. Encabezados restringidos

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

  • No x-amzn- se permiten los 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 acceso entrantecustomJWTAuthorizer. OAuth-based

  • El valor 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 sin distinción entre 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 que se propaguen:

Categoría Encabezados

Autenticación y autorización

Proxy-Authorization, WWW-Authenticate

Negociación de contenido

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

Almacenamiento en caché

Cache-Control, eTag, Caduca, 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, De

Alcance/transferencia

Alcance Accept-Ranges, TE Transfer-Encoding, 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

CORS

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

Suplantació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 comienzan con 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 comienzan con x-amzn- están restringidos, excepto los encabezados con el prefijo. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

Paso 1: Crea tu agente

Crea un AgentCore proyecto vacío y, a continuación, agrega un agente con la lista de permitidos en el encabezado de la solicitud:

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

Actualiza el archivo de puntos de entrada de tu 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", "")
    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()

Paso 2: Configure e implemente su agente con encabezados personalizados

Configure la lista de encabezados de solicitud permitidos en el tiempo 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. El agentcore add agent comando del paso 1 almacena la lista de permitidos en la configuración del tiempo de ejecución, en. runtimes agentcore/agentcore.json

    Despliegue su agente:

    agentcore deploy

    Observe el ARN en tiempo de ejecución del agente en la salida. Lo necesitas si planeas invocar con el AWS SDK.

AWS SDK

  1. Tras implementar el agente, actualice la configuración del tiempo de ejecución con 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.

    Puedes encontrar tu ID de tiempo de ejecución ejecutandoagentcore 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 los controladores de eventos para agregar encabezados personalizados a la invocación de tu agente. Para obtener más información sobre los eventos de botocore, consulta la documentación de los eventos de 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)))

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

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

ejemplo
AgentCore CLI

  1. Para usar la autenticación JWT, ejecuta el siguiente comando en lugar del agentcore add agent comando del paso 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

    Implemente para aplicar la configuración:

    agentcore deploy

    Con esta configuración, el Authorization encabezado de las solicitudes entrantes se valida con respecto a 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.