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.

AG-UI contrato protocolario

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

Para ver un ejemplo de código, 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 de contenedores

Su AG-UI agente debe implementarse como una aplicación en contenedores 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 las invocaciones cumple varios propósitos clave:

Formato de las solicitudes

Amazon Bedrock AgentCore transfiere las cargas útiles de las solicitudes directamente a su contenedor sin necesidad de validarlas. Para ser así AG-UI-compliant, sus solicitudes deben seguir el RunAgentInput formato. 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 de los mensajes, 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 listo para atender 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 Healthy oHealthyBusy. Mientras el estado seaHealthyBusy, la sesión 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 del portador en los encabezados de las solicitudes:

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

Autenticación Sigv4

La autenticación AWS Sigv4 estándar también es compatible con el acceso programático.

Gestión de errores

AG-UI serializa cada error como un RUN_ERROR evento SSE (Content-Type: text/event-stream), independientemente de que el error se produzca antes o durante la transmisión. Las categorías solo difieren en el código de estado HTTP que acompaña al evento:

La siguiente tabla asigna cada excepción de tiempo de ejecución a AG-UI su código de error SSE, código de estado HTTP y mensaje. Algunas excepciones comparten un código de error de SSE, pero devuelven mensajes diferentes, por lo que aparecen en filas independientes.

ConflictExceptiony RetryableConflictException ambos utilizan el código SESSION_BUSY de error SSE (HTTP 409), pero se distinguen por su mensaje. El servicio devuelve RetryableConflictException (Session operation in progress, please retry) cuando una segunda operación llega a una sesión mientras el servicio está aprovisionando o cancelando esa sesión. Es transitorio y se puede volver a intentar: vuelva a intentarlo con un breve retraso exponencial, ya que los clientes no lo reintentan automáticamente. AG-UI

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

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

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

Ejemplo de error con la sesión ocupada (conflicto que se puede volver a intentar):

HTTP/1.1 409 Conflict
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"SESSION_BUSY","message":"Session operation in progress, please retry"}

Respuestas de autenticación de OAuth

OAuth-configured los agentes devuelven los errores de autenticación con códigos de estado HTTP estándar. La respuesta incluye un WWW-Authenticate encabezado (según la 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: 12345678-1234-1234-1234-123456789012

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 los encabezados.