Contrato de protocolo A2A

O contrato de 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 de código, consulte Implantar servidores A2A no AgentCore Runtime.

Requisitos de implementação do protocolo

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

Requisitos de contêiner

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

Requisitos de caminho

/- POSTAR

Finalidade

Recebe mensagens JSON-RPC 2.0 e as processa por meio dos recursos do seu agente, passagem completa da carga útil da InvokeAgentRuntimeAPI 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 cartão de agente para descoberta de agentes e anúncio de recursos

Casos de uso

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

Formato de resposta

Retorna metadados JSON que descrevem 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 relatar quando a status última alteração foi feita.

Requisitos de autenticação

Os servidores A2A oferecem suporte a vários mecanismos de autenticação:

Tokens de portador do OAuth 2.0

Para autenticação do cliente A2A, inclua o token do portador 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 com códigos de status HTTP 200 para manter a conformidade do protocolo:

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