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 A2A

O contrato do protocolo A2A define os requisitos para implementar a comunicação entre agentes no Amazon Bedrock Runtime. AgentCore Este contrato especifica os requisitos técnicos, os endpoints e os padrões de comunicação que seu servidor A2A deve implementar.

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

Requisitos de implementação do protocolo

Seu servidor A2A deve implementar esses requisitos de protocolo específicos:

Requisitos de container

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

Requisitos de caminho

/- POSTAGEM

Finalidade

Recebe mensagens JSON-RPC 2.0 e as processa por meio dos recursos do seu agente, passagem completa da carga útil da InvokeAgentRuntime API com mensagens do protocolo A2A

Casos de uso

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

Formato de solicitação

Os servidores A2A esperam solicitações formatadas JSON-RPC 2.0:

Content-Type: application/json
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Your message content here"
        }
      ],
      "messageId": "unique-message-id"
    }
  }
}

Formato de resposta

Os servidores A2A respondem com respostas formatadas JSON-RPC 2.0 contendo tarefas e artefatos:

Content-Type: application/json
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "artifacts": [
      {
        "artifactId": "unique-artifact-id",
        "name": "agent_response",
        "parts": [
          {
            "kind": "text",
            "text": "Agent response content"
          }
        ]
      }
    ]
  }
}

/.well- -card.json - OBTER known/agent

Finalidade

Fornece metadados do Agent Card para descoberta de agentes e anúncio de capacidades

Casos de uso

O endpoint do Agent Card serve a vários propósitos principais:

Formato de resposta

Retorna metadados JSON descrevendo a identidade e os recursos do agente:

Content-Type: application/json
{
  "name": "Agent Name",
  "description": "Agent description and purpose",
  "version": "1.0.0",
  "url": "https://bedrock-agentcore.region.amazonaws.com/runtimes/agent-arn/invocations/",
  "protocolVersion": "0.3.0",
  "preferredTransport": "JSONRPC",
  "capabilities": {
    "streaming": true
  },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "skills": [
    {
      "id": "skill-id",
      "name": "Skill Name",
      "description": "Skill description and capabilities",
      "tags": []
    }
  ]
}

/ping - OBTER

Finalidade

Verifica se seu servidor A2A 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

Os servidores A2A suportam vários mecanismos de autenticação:

Tokens portadores do OAuth 2.0

Para autenticação do cliente A2A, 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

Os servidores A2A retornam erros como respostas de erro padrão JSON-RPC 2.0. A tabela a seguir mapeia cada exceção de tempo de execução para seu código de JSON-RPC erro, código de status HTTP e mensagem. Algumas exceções compartilham um código de JSON-RPC erro, mas retornam mensagens diferentes, então elas são listadas como linhas separadas.

ConflictExceptione RetryableConflictException ambos usam código JSON-RPC de erro -32054 (HTTP 409). Suas mensagens 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. O chamador deve tentar novamente com um pequeno recuo exponencial, porque os clientes A2A não tentam novamente automaticamente.

Exemplo de resposta de erro:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32052,
    "message": "Validation error - Invalid request data"
  }
}

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 - Autenticação ausente

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