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.

Contrato de protocolo HTTP

Comprenda los requisitos para implementar el protocolo HTTP en la aplicación de su agente. Utilice el protocolo HTTP para crear puntos de enlace directos de la API REST para los request/response patrones tradicionales y puntos de WebSocket enlace para las conexiones de streaming bidireccionales en tiempo real.

Para ver un ejemplo de código, consulte Introducción a la CLI. AgentCore

Requisitos de contenedores

Su agente debe implementarse como una aplicación en contenedores que cumpla con estas especificaciones:

Requisitos de ruta

/invocations - POST

Este es el punto final principal de interacción del agente con entrada y JSON/SSE salida JSON.

Finalidad

Recibe las solicitudes entrantes de los usuarios o las aplicaciones y las procesa mediante la lógica empresarial de su agente

Casos de uso

El /invocations punto final cumple varios propósitos clave:

Ejemplo de formato de solicitud

Content-Type: application/json

{
  "prompt": "What's the weather today?"
}

Formatos de respuesta

Su agente puede responder con cualquiera de los siguientes formatos, según el caso de uso:

Respuesta JSON (sin transmisión)

Finalidad

Proporciona respuestas completas a las solicitudes que se pueden procesar rápidamente

Casos de uso

Las respuestas JSON son ideales para:

Ejemplo de formato de respuesta JSON

Content-Type: application/json

{
  "response": "Your agent's response here",
  "status": "success"
}

Respuesta SSE (transmisión)

Server-sent los eventos (SSE) le permiten ofrecer respuestas de transmisión en tiempo real. Para obtener más información, consulte la especificación de Server-sent eventos.

Finalidad

Permite la entrega de respuestas incrementales para operaciones de larga duración y mejora la experiencia del usuario

Casos de uso

Las respuestas de la SSE son ideales para:

Ejemplo de formato de respuesta SSE

Content-Type: text/event-stream

data: {"event": "partial response 1"}
data: {"event": "partial response 2"}
data: {"event": "final response"}

/ws - WebSocket (Opcional)

Este es el punto final de WebSocket conexión principal para la comunicación bidireccional en tiempo real.

Finalidad

Acepta solicitudes de WebSocket actualización y mantiene conexiones persistentes para las interacciones entre los agentes de streaming

Casos de uso

El /ws punto final cumple varios propósitos clave:

Establecimiento de conexión

WebSocket las conexiones comienzan con una solicitud de actualización HTTP:

Ejemplo de solicitud de actualización de HTTP

GET /ws HTTP/1.1
Host: agent-endpoint
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-uuid

Ejemplo de respuesta WebSocket de actualización

HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

Requisitos de manejo de mensajes

Su WebSocket terminal debe gestionar:

Formatos de mensajes

Mensajes de texto

Formato JSON (recomendado)

Finalidad

Intercambio estructurado de datos para las interacciones entre agentes

Ejemplo de mensaje

{
  "prompt": "Hello, can you help me with this question?",
  "session_id": "session-uuid",
  "message_type": "user_message"
}

Ejemplo de respuesta

{
  "response": "I'd be happy to help you with your question!",
  "session_id": "session-uuid",
  "message_type": "agent_response"
}

Formato de texto plano

Finalidad

Comunicación simple basada en texto

Ejemplo

Hello, can you help me with this question?

Mensajes binarios

Finalidad

Soporte para datos no textuales, como imágenes, audio u otros formatos binarios

Casos de uso

Los mensajes binarios admiten varios escenarios:

Requisitos de manejo

La gestión de mensajes binarios requiere:

Ciclo vital de conexión

Establecimiento de la conexión

Intercambio de mensajes

/ping - OBTENER

Finalidad

Verifica que su agente esté operativo y listo para atender las solicitudes

Casos de uso

El /ping punto final cumple varios propósitos clave:

Formato de las respuestas

Devuelve un código de estado que indica el estado de su agente:

Si tu agente necesita procesar tareas en segundo plano, puedes indicarlo con el /ping estado. Si el estado del ping esHealthyBusy, la sesión de ejecución se considera activa.

Ejemplo de formato de respuesta de ping

{
  "status": "<status_value>"
}

Gestión de errores

A diferencia del A2A, el MCP y AG-UI los protocolos, el protocolo HTTP no envuelve los errores en un sobre específico del protocolo. El servicio devuelve los errores directamente como respuestas HTTP nativas: el código de estado HTTP refleja la excepción y el encabezado de la x-amzn-ErrorType respuesta lleva el nombre de la excepción. En la siguiente tabla se enumeran las excepciones que puede recibir.

ConflictExceptiony RetryableConflictException ambos devuelven HTTP 409. El x-amzn-ErrorType encabezado y el mensaje los distinguen. El servicio devuelve RetryableConflictException (Session operation in progress, please retry) cuando una segunda operación se dirige a una sesión que el servicio está aprovisionando o desactivando. Esta condición es transitoria y se puede volver a intentar. Vuelva a intentarlo con un breve retroceso exponencial. Los AWS SDK reintentan automáticamente esta excepción cuando están habilitados los reintentos predeterminados. Si llamas a la API directamente sin un AWS SDK, debes volver a intentarlo tú mismo.

Respuestas de autenticación de OAuth

OAuth-configured los agentes siguen los estándares de autenticación RFC 6749 (OAuth 2.0). Cuando falta la autenticación, el servicio devuelve una respuesta no autorizada 401 con un WWW-Authenticate encabezado (según la RFC 7235), lo que permite a los clientes descubrir los puntos finales del servidor de autorización a través de la API. GetRuntimeProtectedResourceMetadata

401 sin autorización

Se devuelve cuando falta el encabezado de autorización.

Incluye WWW-Authenticate encabezado:

WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"