A2A Protocol

Integre agentes usando o protocolo Agent-to-Agent para comunicação padronizada entre agentes de IA

Visão Geral

O Agent-to-Agent Protocol (A2A) é um protocolo padronizado desenvolvido pelo Google para permitir comunicação estruturada entre agentes de IA independentes. Utilizando JSON-RPC 2.0 sobre HTTP/HTTPS, o A2A facilita a interoperabilidade entre diferentes sistemas de agentes, permitindo que trabalhem em conjunto de forma eficiente.

Protocolo Oficial: O A2A é mantido pelo Google e está disponível em google.github.io/A2A. O código fonte pode ser encontrado no repositório GitHub.

Características Principais

JSON-RPC 2.0

Protocolo baseado em JSON-RPC 2.0 para comunicação estruturada e padronizada

Multi-turn

Suporte nativo a conversas com múltiplos turnos usando contextId

Upload de Arquivos

Transferência de arquivos via Base64 com suporte a diferentes tipos MIME

Streaming

Comunicação assíncrona via Server-Sent Events (SSE) para respostas em tempo real

Visão Geral Rápida

Ponto-chave	Resumo
Objetivo	Padronizar a conversa entre agentes de IA (independentemente do fornecedor) usando JSON-RPC 2.0
Formato base	Cada chamada é um objeto JSON com jsonrpc:"2.0", id, method e params
Métodos principais	message/send • message/stream • tasks/get • tasks/cancel • tasks/pushNotificationConfig/{set|get} • tasks/resubscribe • agent/authenticatedExtendedCard
IDs obrigatórios	messageId (UUID v4) dentro de cada mensagem e id/taskId/callId para rastrear requisição e tarefa
Recursos de 1ª classe	Conversas multi-turn (contextId) • Upload de arquivos (parts[] tipo file com Base64 + MIME) • Notificações Push via pushNotificationConfig • Autenticação por x-api-key ou Authorization: Bearer
Ciclo de vida da tarefa	submitted → working → completed / failed / canceled, relatado em result.status.state

Métodos do Protocolo

message/send (HTTP Síncrono)

O método principal para enviar mensagens de forma síncrona.

Estrutura da Requisição

POST /api/v1/a2a/AGENT-ID
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "Olá, quem é você?" }],
      "messageId": "6dbc13b5-bd57-4c2b-b503-24e381b6c8d6"
    },
    "sessionId": "session-789",    // opcional, para multi-turn
    "id": "task-456"               // taskId opcional
  }
}

Resposta Típica

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-456",
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [{ "type": "text", "text": "Sou um agente A2A pronto para ajudar!" }]
      }
    },
    "final": true
  },
  "id": "req-001"
}

message/stream (SSE Assíncrono)

Para comunicação em tempo real com streaming de respostas.

Requisição Inicial

POST /api/v1/a2a/AGENT-ID
Content-Type: application/json
Accept: text/event-stream
x-api-key: YOUR_API_KEY

{
  "jsonrpc": "2.0",
  "id": "req-002",
  "method": "message/stream",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "Gere um relatório detalhado" }],
      "messageId": "uuid-here"
    }
  }
}

Eventos SSE

data: {"jsonrpc":"2.0","id":"req-002",
       "result":{"id":"task-789",
                 "status":{"state":"working"},
                 "final":false}}

data: {"jsonrpc":"2.0","id":"req-002",
       "result":{"id":"task-789",
                 "status":{"state":"completed",
                           "message":{"role":"agent",
                                      "parts":[{"type":"text","text":"Aqui está seu relatório..."}]}},
                 "final":true}}

Exemplos de Implementação

cURL

message/send

curl -X POST http://localhost:8000/api/v1/a2a/AGENT-ID \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "Olá!"}],
        "messageId": "6dbc13b5-bd57-4c2b-b503-24e381b6c8d6"
      }
    }
  }'

JavaScript / Fetch

message/send

const payload = {
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{"type": "text", "text": "Explique o protocolo A2A"}],
      "messageId": crypto.randomUUID()
    }
  }
};

const response = await fetch('/api/v1/a2a/AGENT-ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify(payload)
});

const result = await response.json();
console.log(result);

Python

message/send

import requests
import uuid
import json

payload = {
    "jsonrpc": "2.0",
    "id": str(uuid.uuid4()),
    "method": "message/send",
    "params": {
        "message": {
            "role": "user",
            "parts": [{"type": "text", "text": "Explique o protocolo A2A"}],
            "messageId": str(uuid.uuid4())
        }
    }
}

response = requests.post(
    "http://localhost:8000/api/v1/a2a/AGENT-ID",
    headers={"x-api-key": "YOUR_API_KEY"},
    json=payload
)

print(json.dumps(response.json(), indent=2, ensure_ascii=False))

Upload de Arquivos

O protocolo A2A suporta upload de arquivos através do tipo file em parts:

{
  "jsonrpc": "2.0",
  "id": "req-003",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Analise esta imagem"
        },
        {
          "type": "file",
          "file": {
            "name": "imagem.png",
            "mimeType": "image/png",
            "bytes": "iVBORw0KGgoAAAANSUhEUgAAAAUA..." // Base64 sem cabeçalho
          }
        }
      ],
      "messageId": "uuid-here"
    }
  }
}

Formato Base64: Os arquivos devem ser codificados em Base64 sem o cabeçalho data:mime/type;base64,. Apenas o conteúdo Base64 puro deve ser incluído no campo bytes.

Conversas Multi-turn

Para manter contexto entre múltiplas mensagens, use o contextId:

Primeira mensagem

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{"type": "text", "text": "Meu nome é João"}],
      "messageId": "msg-001"
    }
  }
}

Resposta:

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-001",
    "contextId": "ctx-abc123", // Guardar este ID
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [{"type": "text", "text": "Olá João! Como posso ajudá-lo?"}]
      }
    }
  }
}

Mensagem subsequente

{
  "jsonrpc": "2.0",
  "id": "req-002",
  "method": "message/send",
  "params": {
    "contextId": "ctx-abc123", // Usar o contextId anterior
    "message": {
      "role": "user",
      "parts": [{"type": "text", "text": "Qual é o meu nome?"}],
      "messageId": "msg-002"
    }
  }
}

Resposta:

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-002",
    "contextId": "ctx-abc123",
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [{"type": "text", "text": "Seu nome é João!"}]
      }
    }
  }
}

Estados da Tarefa

O protocolo A2A define estados específicos para o ciclo de vida das tarefas:

Estado	Descrição
submitted	Tarefa foi recebida e está na fila
working	Tarefa está sendo processada
completed	Tarefa foi concluída com sucesso
failed	Tarefa falhou durante o processamento
canceled	Tarefa foi cancelada pelo usuário

Autenticação

O protocolo suporta diferentes métodos de autenticação:

API Key

x-api-key: YOUR_API_KEY

x-api-key: YOUR_API_KEY

Authorization: Bearer YOUR_TOKEN

Dicas e Boas Práticas

IDs únicos

• Use UUID v4 para todos os IDs obrigatórios (messageId, id, etc.)
• Mantenha consistência nos IDs para rastreamento adequado

Multi-turn

• Sempre guarde o contextId retornado para conversas contínuas
• Envie o contextId em todas as mensagens subsequentes da mesma conversa

Arquivos

• Use Base64 sem cabeçalho no campo bytes
• Especifique sempre o mimeType correto
• Considere o tamanho máximo suportado pelo servidor

Streaming

• Trate eventos de ping (: ping) adequadamente
• Feche a conexão EventSource quando final: true
• Implemente tratamento de reconexão para robustez

CORS

• Configure CORS no servidor (Access-Control-Allow-Origin: *) para testes no navegador
• Use headers apropriados para produção

Recursos Adicionais

Especificação Oficial

Documentação completa do protocolo A2A mantida pelo Google

Repositório GitHub

Código fonte, exemplos e issues do projeto A2A

Guia de Início Rápido

Configure seu primeiro agente em menos de 2 minutos

Tipos de Agentes

Explore diferentes tipos de agentes compatíveis com A2A

---

Com o protocolo A2A, você pode integrar rapidamente qualquer agente ou aplicação front-end ao ecossistema Evo AI, garantindo interoperabilidade e comunicação padronizada entre diferentes sistemas de agentes de IA.