AG-UI contrato de protocolo

O contrato de AG-UI protocolo define os requisitos para implementar a comunicação da interface do agente para o usuário no Amazon Bedrock Runtime. AgentCore Esse contrato especifica os requisitos técnicos, os endpoints e os padrões de comunicação que seu AG-UI agente deve implementar.

Por exemplo de código, consulte Implantar AG-UI servidores no AgentCore Runtime.

Requisitos de implementação do protocolo

Seu AG-UI agente deve implementar esses requisitos específicos de protocolo:

Requisitos de contêiner

Seu AG-UI agente deve ser implantado como um aplicativo em contêiner que atenda às seguintes especificações:

Requisitos de caminho

/invocações - POST

Finalidade

Recebe solicitações de usuários e transmite respostas como Server-Sent eventos (SSE)

Casos de uso

O endpoint de invocações serve a vários propósitos principais:

Formato de solicitação

O Amazon Bedrock AgentCore passa as cargas de solicitação diretamente para seu contêiner sem validação. Para ser AG-UI-compliant, suas solicitações devem seguir o RunAgentInput formato. Sua implementação de contêiner determina quais campos são obrigatórios e como os erros de validação são tratados.

AG-UI-compliant os agentes esperam uma carga RunAgentInput JSON. Exemplo:

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

Para obter os detalhes completos do RunAgentInput esquema e do formato da mensagem, consulte AG-UI Tipos.

Formato de resposta

AG-UI os agentes respondem com fluxos 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

Finalidade

Fornece comunicação bidirecional em tempo real entre clientes e agentes

Casos de uso

O WebSocket endpoint serve a vários propósitos principais:

/ping - OBTER

Finalidade

Verifica se seu AG-UI agente está operacional e pronto para lidar com as solicitações

Formato de resposta

Retorna um código de status indicando a saúde do seu agente:

{
  "status": "Healthy"
}

statusé obrigatório e é um dos Healthy ouHealthyBusy. Enquanto o status forHealthyBusy, a sessão de tempo de execução é mantida ativa.

Um time_of_last_update campo opcional (um carimbo de data/hora do Unix em segundos) pode ser incluído para relatar quando a status última alteração foi feita.

Requisitos de autenticação

AG-UI os agentes oferecem suporte a vários mecanismos de autenticação:

Tokens de portador do OAuth 2.0

Para autenticação AG-UI do cliente, inclua o token do portador nos cabeçalhos da solicitação:

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

Autenticação SigV4

A autenticação AWS SigV4 padrão também é suportada para acesso programático.

Tratamento de erros

Os erros são classificados em duas categorias com base em quando eles ocorrem:

Exemplo de erro de tempo de execução (falha do 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"}

Respostas de autenticação OAuth

OAuth-configured os agentes retornam erros de autenticação com códigos de status HTTP padrão. A resposta inclui um WWW-Authenticate cabeçalho (de acordo com a RFC 7235) para a descoberta do OAuth por meio da API. GetRuntimeProtectedResourceMetadata

Exemplo de erro de autenticação 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 os agentes retornam HTTP 403 com um ACCESS_DENIED erro e não incluem WWW-Authenticate cabeçalhos.