Contrato de protocolo HTTP

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

Para ver código de ejemplo, consulte Comenzar con la AgentCore CLI.

Requisitos de contenedores

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

Requisitos de ruta

/invocations - POST

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

Finalidad

Recibe las solicitudes entrantes de los usuarios o las aplicaciones y las procesa según 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 mediante uno 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 streaming en tiempo real. Para obtener más información, consulte la especificación de Server-sent los eventos.

Finalidad

Permite ofrecer una respuesta incremental para operaciones de larga duración y mejorar la experiencia del usuario

Casos de uso

Las respuestas 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 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 de datos estructurado para las interacciones entre los 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 sencilla basada en texto

Ejemplo

Hello, can you help me with this question?

Mensajes binarios

Finalidad

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

Casos de uso

Los mensajes binarios admiten varios escenarios:

Requisitos de manejo

El manejo de mensajes binarios requiere:

Ciclo de vida de

Establecimiento de conexión

Intercambio de mensajes

/ping - OBTENER

Finalidad

Verifica que su agente esté operativo y preparado para gestionar 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 salud de su agente:

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

Ejemplo de formato de respuesta de ping

{
  "status": "<status_value>"
}

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 401 no autorizada 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}"