AG-UI contrato protocolario

El contrato de AG-UI protocolo define los requisitos para implementar la comunicación de la interfaz de agente a usuario en Amazon Bedrock Runtime. AgentCore Este contrato especifica los requisitos técnicos, los puntos finales y los patrones de comunicación que su agente debe implementar. AG-UI

Para ver un código de ejemplo, consulte Implementar AG-UI servidores en AgentCore tiempo de ejecución.

Requisitos de implementación del protocolo

Su AG-UI agente debe implementar estos requisitos de protocolo específicos:

Requisitos del contenedor

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

Requisitos de ruta

/invocations - POST

Finalidad

Recibe las solicitudes de los usuarios y transmite las respuestas como Server-Sent eventos (SSE)

Casos de uso

El punto final de invocaciones cumple varios propósitos clave:

Formato de las solicitudes

Amazon Bedrock AgentCore transfiere las cargas útiles solicitadas directamente a su contenedor sin necesidad de validarlas. Para ello AG-UI-compliant, sus solicitudes deben seguir este formato. RunAgentInput La implementación de su contenedor determina qué campos son obligatorios y cómo se gestionan los errores de validación.

AG-UI-compliant los agentes esperan una carga útil de RunAgentInput JSON. Ejemplo:

{
  "threadId": "thread-123",
  "runId": "run-456",
  "messages": [{"id": "msg-1", "role": "user", "content": "Hello, agent!"}],
  "tools": [],
  "context": [],
  "state": {},
  "forwardedProps": {}
}

Para ver los detalles completos RunAgentInput del esquema y el formato del mensaje, consulta AG-UI Tipos.

Formato de las respuestas

AG-UI los agentes responden con secuencias de SSE-formatted eventos:

Content-Type: text/event-stream

data: {"type":"RUN_STARTED","threadId":"thread-123","runId":"run-456"}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-789","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-789","delta":"Processing your request"}

data: {"type":"TOOL_CALL_START","toolCallId":"tool-001","toolCallName":"search","parentMessageId":"msg-789"}

data: {"type":"TOOL_CALL_RESULT","messageId":"msg-789","toolCallId":"tool-001","content":"Search completed"}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-789"}

data: {"type":"RUN_FINISHED","threadId":"thread-123","runId":"run-456"}

/ws - WebSocket

Finalidad

Proporciona comunicación bidireccional en tiempo real entre clientes y agentes

Casos de uso

El WebSocket punto final cumple varios propósitos clave:

/ping - OBTENER

Finalidad

Verifica que su AG-UI agente esté operativo y preparado para gestionar las solicitudes

Formato de las respuestas

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

{
  "status": "Healthy"
}

statuses obligatorio y es uno de los Healthy siguientesHealthyBusy: Mientras el estado seaHealthyBusy, la sesión en tiempo de ejecución se mantiene activa.

Se puede incluir un time_of_last_update campo opcional (una marca de tiempo de Unix en segundos) para indicar cuándo se modificó por última vez. status

Requisitos de autenticación

AG-UI los agentes admiten varios mecanismos de autenticación:

Tokens portadores de OAuth 2.0

Para la autenticación AG-UI del cliente, incluye el token Bearer en los encabezados de las solicitudes:

Authorization: Bearer <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>

Autenticación SigV4

También se admite la autenticación AWS SigV4 estándar para el acceso programático.

Gestión de errores

Los errores se clasifican en dos categorías según el momento en que se producen:

Ejemplo de error de tiempo de ejecución (fallo del agente):

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

data: {"type":"RUN_ERROR","code":"AGENT_ERROR","message":"Agent execution failed"}

Respuestas de autenticación de OAuth

OAuth-configured los agentes devuelven errores de autenticación con códigos de estado HTTP estándar. La respuesta incluye un WWW-Authenticate encabezado (según el RFC 7235) para detectar OAuth a través de la API. GetRuntimeProtectedResourceMetadata

Ejemplo de error de autenticación de OAuth:

HTTP/1.1 401 Unauthorized
Content-Type: text/event-stream
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
x-amzn-requestid: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

data: {"type":"RUN_ERROR","code":"UNAUTHORIZED","message":"Authentication required"}

SigV4-configured los agentes devuelven el HTTP 403 con un ACCESS_DENIED error y no incluyen WWW-Authenticate encabezados.