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 Comece a usar a AgentCore CLI.

Requisitos de contêiner

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 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:

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 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 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:

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 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:

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:

Formatos de mensagem

Mensagens de texto

Formato JSON (recomendado)

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

Finalidade

Comunicação simples baseada em texto

Exemplo

Hello, can you help me with this question?

Mensagens binárias

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:

Requisitos de manuseio

O tratamento de mensagens binárias requer:

Ciclo de vida da conexão

Estabelecimento de

Troca de mensagens

/ping - OBTER

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:

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

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