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á.

Contrato de protocolo HTTP

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.

Por exemplo, código, consulte Começar a usar a AgentCore CLI.

Requisitos de container

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

Requisitos de caminho

/invocações - POST

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

Finalidade

Recebe solicitações 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:

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)

Finalidade

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

Casos de uso

As respostas JSON são ideais para:

Exemplo de formato de resposta JSON

Content-Type: application/json

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

Resposta SSE (streaming)

Server-sent os 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.

Finalidade

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

Casos de uso

As respostas do SSE são ideais para:

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)

Esse é o principal terminal 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:

estabelecimento de conexão

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

Exemplo de solicitação de atualização de 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:

Formatos de mensagem

Mensagens de texto

Formato JSON (recomendado)

Finalidade

Troca de dados estruturada para interações com agentes

Exemplo de mensagem

{
  "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 simples

Finalidade

Comunicação simples baseada em texto

Exemplo

Hello, can you help me with this question?

Mensagens binárias

Finalidade

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

Casos de uso

As mensagens binárias suportam vários cenários:

Requisitos de manipulação

O tratamento de mensagens binárias requer:

Ciclo de vida da conexão

estabelecimento de conexão

Troca de mensagens

/ping - OBTENHA

Finalidade

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

Casos de uso

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

Formato de resposta

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

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

Exemplo de formato de resposta Ping

{
  "status": "<status_value>"
}

Tratamento de erros

Diferentemente do A2A, do MCP e dos AG-UI protocolos, o protocolo HTTP não agrupa os erros em um envelope específico do protocolo. O serviço retorna erros diretamente como respostas HTTP nativas: o código de status HTTP reflete a exceção e o cabeçalho da x-amzn-ErrorType resposta carrega o nome da exceção. A tabela a seguir lista as exceções que você pode receber.

ConflictExceptione RetryableConflictException ambos retornam HTTP 409. O x-amzn-ErrorType cabeçalho e a mensagem os distinguem. O serviço retorna RetryableConflictException (Session operation in progress, please retry) quando uma segunda operação tem como alvo uma sessão que o serviço está provisionando ou desativando. Essa condição é transitória e pode ser repetida. Tente novamente com um pequeno recuo exponencial. Os AWS SDKs repetem automaticamente essa exceção quando as novas tentativas padrão estão habilitadas. Se você chamar a API diretamente sem um AWS SDK, você mesmo deverá tentar novamente.

Respostas de autenticação OAuth

OAuth-configured os agentes seguem os padrões de autenticação RFC 6749 (OAuth 2.0). 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), permitindo que os clientes descubram os endpoints do servidor de autorização por meio da API. GetRuntimeProtectedResourceMetadata

401 Não autorizado

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