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](runtime-agui.md).
**Topics**
+ [Requisitos de implementação do protocolo](#agui-protocol-implementation-requirements)
+ [Requisitos de container](#agui-container-requirements)
+ [Requisitos de caminho](#agui-path-requirements)
+ [Requisitos de autenticação](#agui-authentication-requirements)
+ [Tratamento de erros](#agui-error-handling)
+ [Respostas de autenticação OAuth](#agui-oauth-authentication-responses)
## Requisitos de implementação do protocolo
Seu AG-UI agente deve implementar esses requisitos específicos de protocolo:
+ **Transporte**: Server-Sent Eventos (SSE) ou WebSocket - SSE fornece streaming unidirecional do servidor para o cliente, enquanto WebSocket permite a comunicação bidirecional em tempo real
+ **Gerenciamento de sessão**: a plataforma adiciona automaticamente o `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` cabeçalho para isolamento da sessão
## Requisitos de container
Seu AG-UI agente deve ser implantado como um aplicativo em contêiner que atenda às seguintes especificações:
+ **Host**: `0.0.0.0`
+ **Porta**: `8080` - Porta padrão para comunicação com AG-UI agentes (igual ao protocolo HTTP)
+ **Plataforma**: contêiner ARM64 - necessário para compatibilidade com o ambiente de execução AWS Amazon Bedrock AgentCore
## 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:
+ Respostas de bate-papo em streaming
+ Status do agente e etapas de raciocínio
+ Chamadas e resultados de ferramentas
#### 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](https://docs.ag-ui.com/sdk/js/core/types).
#### 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:
+ Real-time interfaces conversacionais
+ Sessões interativas de agentes com interrupções do usuário
+ Multi-turn conversas com conexões persistentes
### /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:
+ **Content-Type** : `application/json`
+ **Código de status HTTP**: `200` para códigos de erro saudáveis e apropriados para estados não íntegros
```
{
"status": "Healthy"
}
```
`status`é obrigatório e é um dos `Healthy` ou`HealthyBusy`. Enquanto o status for`HealthyBusy`, 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.
**Atenção**
Não `time_of_last_update` defina a hora atual em cada ping. Um carimbo de data/hora que avança a cada ping sinaliza uma mudança contínua de status, o que impede que o tempo limite da sessão ociosa seja acionado — as sessões então persistem até `MaxLifetime` esgotar sua cota de sessão. Se você omitir o campo, a plataforma rastreará as alterações de status sozinha. Se você usa o Bedrock AgentCore SDK, a resposta do ping é tratada para você.
## 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
X-Amzn-Bedrock-AgentCore-Runtime-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:
+ **Connection-level erros**: ocorrem antes que a solicitação chegue ao seu contêiner (autenticação, autorização, validação, limitação, conflitos de sessão). O `RUN_ERROR` evento é retornado com o código de status HTTP real do erro (por exemplo, 401, 403 ou 409).
+ **Erros de tempo de execução**: ocorrem durante a execução do agente após o início do stream. Só `AGENT_ERROR` se enquadra nessa categoria. Seu `RUN_ERROR` evento retorna HTTP 200 porque o fluxo já começou.
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.
| Código de erro SSE | Exceção de execução | Código de erro HTTP | Mensagem de erro |
| --- | --- | --- | --- |
| `UNAUTHORIZED` | UnauthorizedException | 401 | Autenticação necessária ou credenciais inválidas |
| `ACCESS_DENIED` | AccessDeniedException | 403 | Permissões insuficientes para a operação solicitada |
| `VALIDATION_ERROR` | ValidationException | 400 | Dados ou parâmetros de solicitação inválidos |
| `RATE_LIMIT_EXCEEDED` | ThrottlingException | 429 | Muitas solicitações do cliente |
| `SESSION_BUSY` | ConflictException | 409 | Conflito de recursos - O recurso já existe |
| `SESSION_BUSY` | RetryableConflictException | 409 | Operação da sessão em andamento, tente novamente |
| `SERVICE_QUOTA_EXCEEDED` | ServiceQuotaExceededException | 429 | Cota de serviço excedida |
| `AGENT_ERROR` | RuntimeClientError | 200 | O código do agente falhou durante a execução — verifique seus CloudWatch registros |
| `INTERNAL_ERROR` | Qualquer outra exceção | 500 | Ocorreu um erro interno ao processar a solicitação |
`ConflictException`e `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](https://datatracker.ietf.org/doc/html/rfc7235)) 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.