As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

AG-UI contrato de protocolo

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

Por exemplo, código, consulte Implantar AG-UI servidores em AgentCore tempo de execução.

Requisitos de implementação do protocolo

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

Requisitos de container

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 o 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 útil 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 - OBTENHA

Finalidade

Verifica se seu AG-UI agente está operacional e pronto para lidar com 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 informar 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 portadores do OAuth 2.0

Para autenticação AG-UI do cliente, inclua o token Bearer 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

AG-UI serializa cada erro como um RUN_ERROR evento SSE (Content-Type: text/event-stream), independentemente de o erro ocorrer antes ou durante o streaming. As categorias diferem somente no código de status HTTP que acompanha o evento:

A tabela a seguir mapeia cada exceção de tempo de execução para seu código de erro AG-UI SSE, código de status HTTP e mensagem. Algumas exceções compartilham um código de erro SSE, mas retornam mensagens diferentes, então elas são listadas como linhas separadas.

ConflictExceptione RetryableConflictException ambos usam o código de erro SESSION_BUSY SSE (HTTP 409), mas são diferenciados por sua mensagem. O serviço retorna RetryableConflictException (Session operation in progress, please retry) quando uma segunda operação atinge uma sessão enquanto o serviço está provisionando ou desativando essa sessão. É transitório e pode ser repetido — tente novamente com um pequeno recuo exponencial, porque AG-UI os clientes não o fazem automaticamente.

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

Exemplo de erro de sessão ocupada (conflito que pode ser repetido):

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"}

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 descoberta de 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: 12345678-1234-1234-1234-123456789012

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.