# Contrato de protocolo HTTP
<a name="runtime-http-protocol-contract"></a>

Entenda os requisitos para implementar o protocolo HTTP em seu aplicativo de agente. Use o protocolo HTTP para criar endpoints diretos da API REST para request/response padrões tradicionais e WebSocket endpoints para conexões de streaming bidirecionais em tempo real.

**nota**  
Os endpoints HTTP (`/invocations`) e WebSocket (`/ws`) podem ser implantados no mesmo contêiner usando a porta 8080, permitindo que a implementação de um único agente ofereça suporte às interações tradicionais da API e ao streaming bidirecional em tempo real.

Por exemplo, código, consulte [Comece a usar a AgentCore CLI](runtime-get-started-cli.md).

**Topics**
+ [Requisitos de contêiner](#container-requirements-http)
+ [Requisitos de caminho](#path-requirements-http)
+ [Respostas de autenticação OAuth](#http-oauth-authentication-responses)

## Requisitos de contêiner
<a name="container-requirements-http"></a>

Seu 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 HTTP-based do agente
+  **Plataforma**: contêiner ARM64 - necessário para compatibilidade com o AgentCore ambiente Runtime

## Requisitos de caminho
<a name="path-requirements-http"></a>

### /invocações - POST
<a name="invocations-endpoint"></a>

Esse é o principal endpoint de interação do agente com entrada e JSON/SSE saída JSON.

 **Finalidade** 

Recebe solicitações recebidas de usuários ou aplicativos e as processa por meio da lógica de negócios do seu agente

 **Casos de uso** 

O `/invocations` endpoint serve a vários propósitos principais:
+ Interações e conversas diretas do usuário
+ Integrações de API com sistemas externos
+ Processamento em lote de várias solicitações
+ Real-time respostas de streaming para operações de longa duração

 **Exemplo de formato de solicitação** 

```
Content-Type: application/json

{
  "prompt": "What's the weather today?"
}
```

 **Formatos de resposta** 

Seu agente pode responder usando um dos seguintes formatos, dependendo do caso de uso:

#### Resposta JSON (sem streaming)
<a name="json-response"></a>

 **Finalidade** 

Fornece respostas completas para solicitações que podem ser processadas rapidamente

 **Casos de uso** 

As respostas JSON são ideais para:
+ Cenários simples de resposta a perguntas
+ Cálculos determinísticos
+ Pesquisas rápidas de dados
+ Confirmações de status

 **Exemplo de formato de resposta JSON** 

```
Content-Type: application/json

{
  "response": "Your agent's response here",
  "status": "success"
}
```

#### Resposta SSE (streaming)
<a name="sse-response"></a>

Server-sent eventos (SSE) permitem que você forneça respostas de streaming em tempo real. Para obter mais informações, consulte a especificação de [Server-sent eventos](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events).

 **Finalidade** 

Permite a entrega de respostas incrementais para operações de longa duração e melhora a experiência do usuário

 **Casos de uso** 

As respostas da SSE são ideais para:
+ Real-time experiências de conversação
+ Geração progressiva de conteúdo
+ Long-running cálculos com resultados intermediários
+ Feeds e atualizações de dados ao vivo

 **Exemplo de formato de resposta SSE** 

```
Content-Type: text/event-stream

data: {"event": "partial response 1"}
data: {"event": "partial response 2"}
data: {"event": "final response"}
```

### /ws - WebSocket (Opcional)
<a name="ws-endpoint"></a>

Esse é o principal ponto final de WebSocket conexão para comunicação bidirecional em tempo real.

 **Finalidade** 

Aceita solicitações de WebSocket upgrade e mantém conexões persistentes para interações com agentes de streaming

 **Casos de uso** 

O `/ws` endpoint serve a vários propósitos principais:
+ Real-time interfaces de conversação
+ Sessões interativas com agentes com feedback imediato
+ Processamento de dados de streaming com comunicação bidirecional

 **estabelecimento de conexão** 

WebSocket as conexões começam com uma solicitação de upgrade HTTP:

 **Exemplo de solicitação de atualização HTTP** 

```
GET /ws HTTP/1.1
Host: agent-endpoint
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-uuid
```

 **Exemplo de resposta de WebSocket atualização** 

```
HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
```

 **Requisitos de tratamento de mensagens** 

Seu WebSocket endpoint deve lidar com:
+  **Aceitação da conexão**: Ligue `await websocket.accept()` para estabelecer a conexão
+  **Recepção de mensagens**: Support tipos de mensagens de texto ou binárias com base nos requisitos do seu aplicativo
+  **Processamento de mensagens**: gerencie as mensagens recebidas de acordo com a lógica de negócios do seu agente
+  **Envio de respostas**: envie respostas apropriadas usando `send_text()` ou `send_bytes()` 
+  **Ciclo de vida da conexão**: gerencie o estabelecimento, a manutenção e o término da conexão

#### Formatos de mensagem
<a name="websocket-message-formats"></a>

##### Mensagens de texto
<a name="websocket-text-messages"></a>

##### Formato JSON (recomendado)
<a name="websocket-json-format"></a>

 **Finalidade** 

Troca estruturada de dados para interações com agentes

 **Mensagem de exemplo** 

```
{
  "prompt": "Hello, can you help me with this question?",
  "session_id": "session-uuid",
  "message_type": "user_message"
}
```

 **Exemplo de resposta** 

```
{
  "response": "I'd be happy to help you with your question!",
  "session_id": "session-uuid",
  "message_type": "agent_response"
}
```

##### Formato de texto sem formatação
<a name="websocket-plain-text-format"></a>

 **Finalidade** 

Comunicação simples baseada em texto

 **Exemplo** 

```
Hello, can you help me with this question?
```

##### Mensagens binárias
<a name="websocket-binary-messages"></a>

 **Finalidade** 

Support para dados não textuais, como imagens, áudio ou outros formatos binários

 **Casos de uso** 

As mensagens binárias oferecem suporte a vários cenários:
+ Multi-modal interações com agentes
+ Uploads e downloads de arquivos
+ Transmissão de dados compactados
+ Dados do protocolo binário

 **Requisitos de manuseio** 

O tratamento de mensagens binárias requer:
+ Uso `receive_bytes()` e `send_bytes()` métodos
+ Implemente o processamento apropriado de dados binários
+ Considere as limitações de tamanho da mensagem

#### Ciclo de vida da conexão
<a name="websocket-connection-lifecycle"></a>

##### Estabelecimento de
<a name="websocket-connection-establishment"></a>

1.  **Handshake HTTP**: o cliente envia uma solicitação de WebSocket atualização

1.  **Resposta de atualização**: o agente aceita e retorna 101 protocolos de comutação

1.  **WebSocket Ativo**: a comunicação bidirecional começa

1.  **Vinculação de sessão**: associe a conexão ao identificador da sessão

##### Troca de mensagens
<a name="websocket-message-exchange"></a>

1.  **Loop contínuo**: implemente o loop de escuta de mensagens

1.  **Processamento de mensagens**: manipule as mensagens recebidas de forma assíncrona

1.  **Geração de respostas**: envie respostas apropriadas

1.  **Tratamento de erros**: gerencie exceções e problemas de conexão

### /ping - OBTER
<a name="ping-endpoint"></a>

 **Finalidade** 

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

 **Casos de uso** 

O `/ping` endpoint serve a vários propósitos principais:
+ Monitoramento de serviços para detectar e corrigir problemas
+ Recuperação automatizada por meio AWS da infraestrutura gerenciada

 **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 íntegros e apropriados para estados não íntegros

Se seu agente precisar processar tarefas em segundo plano, você poderá indicá-las com o `/ping` status. Se o status do ping for`HealthyBusy`, a sessão de tempo de execução será considerada ativa.

 **Exemplo de formato de resposta Ping** 

```
{
  "status": "<status_value>"
}
```

 **status** (obrigatório)  
 `Healthy`- O sistema está pronto para aceitar novos trabalhos  
 `HealthyBusy`- O sistema está operacional, mas atualmente ocupado com tarefas assíncronas. Embora o status seja`HealthyBusy`, a sessão de tempo de execução é considerada ativa e mantida ativa.

 **time\_of\_last\_update (opcional**)  
Carimbo de data/hora Unix (em segundos) de quando a `status` última foi alterada. Defina-o somente em uma mudança de status real.  
Não `time_of_last_update` defina a hora atual em cada ping. Um registro de data e hora que avança a cada ping sinaliza uma mudança contínua de status, o que evita 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 AgentCore SDK do Bedrock, a resposta do ping é tratada para você.

## Respostas de autenticação OAuth
<a name="http-oauth-authentication-responses"></a>

OAuth-configured os agentes seguem os padrões de autenticação [RFC 6749 (OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749)). Quando a autenticação está ausente, o serviço retorna uma resposta 401 não autorizada com um WWW-Authenticate cabeçalho (de acordo com a [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)), permitindo que os clientes descubram os endpoints do servidor de autorização por meio da API. GetRuntimeProtectedResourceMetadata 

### 401 Não autorizado
<a name="http-401-unauthorized"></a>

Retornado quando o cabeçalho de autorização está ausente.

Inclui WWW-Authenticate cabeçalho:

```
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```

**nota**  
SigV4-configured os agentes retornam HTTP 403 com um `ACCESS_DENIED` erro e não incluem `WWW-Authenticate` cabeçalhos.