A2A Protocol - Evo AI

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

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

curl -X POST http://localhost:8000/api/v1/a2a/AGENT-ID \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-002",
    "method": "message/stream",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "Streaming test"}],
        "messageId": "uuid-here"
      }
    }
  }'

JavaScript / Fetch

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);

const payload = {
  "jsonrpc": "2.0",
  "id": "req-002",
  "method": "message/stream",
  "params": {
    "message": {
      "role": "user",
      "parts": [{"type": "text", "text": "Streaming response"}],
      "messageId": crypto.randomUUID()
    }
  }
};

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

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log(data);
      
      if (data.result?.final) {
        return; // Finalizar stream
      }
    }
  }
}

Python

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

import requests
import uuid
import json

payload = {
    "jsonrpc": "2.0",
    "id": str(uuid.uuid4()),
    "method": "message/stream",
    "params": {
        "message": {
            "role": "user",
            "parts": [{"type": "text", "text": "Streaming response"}],
            "messageId": str(uuid.uuid4())
        }
    }
}

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

for line in response.iter_lines():
    if line:
        line_str = line.decode('utf-8')
        if line_str.startswith('data: '):
            data = json.loads(line_str[6:])
            print(json.dumps(data, indent=2, ensure_ascii=False))
            
            if data.get('result', {}).get('final'):
                break

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
Bearer Token

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.

​Visão Geral

​Características Principais

JSON-RPC 2.0

Multi-turn

Upload de Arquivos

Streaming

​Visão Geral Rápida

​Métodos do Protocolo

​message/send (HTTP Síncrono)

​message/stream (SSE Assíncrono)

​Exemplos de Implementação

​cURL

​JavaScript / Fetch

​Python

​Upload de Arquivos

​Conversas Multi-turn

​Estados da Tarefa

​Autenticação

​Dicas e Boas Práticas

​Recursos Adicionais

Especificação Oficial

Repositório GitHub

Guia de Início Rápido

Tipos de Agentes

Visão Geral

Características Principais

Visão Geral Rápida

Métodos do Protocolo

message/send (HTTP Síncrono)

message/stream (SSE Assíncrono)

Exemplos de Implementação

cURL

JavaScript / Fetch

Python

Upload de Arquivos

Conversas Multi-turn

Estados da Tarefa

Autenticação

Dicas e Boas Práticas

Recursos Adicionais