Protocolo A2A para agentes
Superfície Agent2Agent (A2A), agent card, registro, certificados por tarefas, MCP e webhooks.
Agent Trust implementa Agent2Agent (A2A) v1.0.0, permitindo registro de identidade e operações PKI de emissão, renovação e revogação por tarefas.
Agent card#
Cada implantação publica um documento legível por máquina:
GET /.well-known/agent-card.jsonAnuncia endpoints A2A, autenticação aceita (bearerAuth e/ou mtlsAuth) e skills disponíveis. Clientes devem consultá-la ao iniciar.
Autenticação#
| Esquema | Como funciona |
|---|---|
| Bearer / JWT | Authorization: Bearer [jwt] validado com signing secret; claim sub identifica o agente. |
| mTLS | Certificado cliente no listener; SPIFFE URI, subject key identifier ou common name vira identidade. |
| Kerberos | Conta de serviço no domínio via Authorization: Negotiate. |
Auth mode: off (anônimo, identidade por IP), jwt ou oidc (sessão do navegador ou certificado mTLS).
Registrar agente#
POST /a2a/v1/register| Campo | Observações |
|---|---|
| agentId | Identidade única, vinculada ao chamador no primeiro cadastro. |
| displayName / agentCardJson | Nome e capacidades legíveis. |
| publicKeyPem / certThumbprint | Prova exigida pela política; definida pelo cliente, não editável por admin. |
| tags[] | Rótulos para regras e grupos. |
| webhookUrl | Webhook HTTPS outbound opcional para notificações, exige chamador autenticado. |
agentId fica vinculado à identidade do primeiro chamador; outro não pode assumi-lo. IDs devem ser únicos. Agentes na mesma IP sem agentId viram uma identidade.
Chain of Command#
Consulte o guia Chain of Command para swarms com consentimento, skills delegadas, vouchers assinados e relatórios.
Tasks#
Operações de certificado são tasks assíncronas consultáveis:
| Método e caminho | Finalidade |
|---|---|
| POST /a2a/v1/tasks/send | Cria task com mensagem, por exemplo arquivo CSR. |
| GET /a2a/v1/tasks/ | Consulta estado e artifacts. |
| POST /a2a/v1/tasks//cancel | Cancela tarefa em andamento. |
| POST /a2a/v1/tasks//subscribe | Recebe atualizações SSE. |
Envie CSR como file part, consulte até completed e baixe o artifact da cadeia. O tutorial de cadastro próprio mostra o fluxo completo.
Streams e idempotência#
- SSE para message:stream e subscribe.
- X-Idempotency-Key evita tarefas duplicadas ao repetir a mesma chave.
Webhooks#
Agentes podem cadastrar webhook HTTPS outbound em host público com chamador autenticado e receber notificações em vez de consultar. Entregas são verificáveis; falhas aparecem no registro e auditoria.
Ferramentas MCP de Compliance#
Agentes com MCP podem chamar ferramentas compliance do gateway, como verificar prompt antes do modelo e agir sobre allow/deny/flag/mask. Consulte Claude Code, Cursor e MCP.
Estados da tarefa#
| Estado | Significado |
|---|---|
| submitted | Criada, aguardando. |
| working | Em processamento. |
| input-required | Precisa de dados adicionais do agente. |
| completed | Concluída, artifacts disponíveis. |
| canceled | Cancelada por agente ou admin. |
| failed / rejected | Falhou ou foi rejeitada, por exemplo identidade bloqueada. |
| auth-required | Agente precisa autenticar antes de continuar. |