Integração A2A MCP

Repositório Git：A2A MCP

Este repositório demonstra como configurar e usar o a2a-python SDK para criar um servidor e cliente simples que implementam o protocolo a2a, e o servidor do agente é implementado por mcp.

Visão Geral

A2A (Agent2Agent): Um protocolo e SDK para construir agentes de IA interoperáveis.
Este Exemplo: Mostra como executar um servidor e cliente A2A básico, trocar mensagens e visualizar a resposta.

Pré-requisitos

Python 3.13+
uv (para gerenciamento rápido de dependências e execução)
Uma chave API para OpenRouter (definir como OPENROUTER_API_KEY)

Instalação

Clonar o repositório:

git clone https://github.com/sing1ee/a2a-mcp-openrouter
cd https://github.com/sing1ee/a2a-mcp-openrouter

Instalar dependências:
```
uv venv
source .venv/bin/activate
```
Definir variáveis de ambiente:
```
export OPENROUTER_API_KEY=your-openrouter-api-key
```
Ou criar um arquivo .env com:
```
OPENROUTER_API_KEY=your-openrouter-api-key
```
Nota: Você pode obter sua chave API do OpenRouter em https://openrouter.ai/

Executando o Exemplo

1. Iniciar o Servidor

uv run --env-file .env a2a-server

O servidor será iniciado na porta 9999.

Validar o cartão do agente:

2. Executar o Cliente

Em um novo terminal:

uv venv
source .venv/bin/activate
uv run --env-file .env a2a-client --question "O que é o protocolo A2A?"

O cliente se conectará ao servidor e enviará uma solicitação.

3. Visualizar a Resposta

A resposta do cliente será salva em response.xml.

Configuração

O sistema usa a seguinte configuração:

Modelo: google/gemini-flash-1.5 via OpenRouter
URL Base: https://openrouter.ai/api/v1

Estrutura de Arquivos

src/a2a_mcp_openrouter/server/: Implementação do servidor.
src/a2a_mcp_openrouter/client/: Implementação do cliente.
response.xml: Exemplo de resposta do cliente.

Solução de Problemas

Dependências ausentes: Certifique-se de ter o uv instalado.
Erros de chave API: Certifique-se de que OPENROUTER_API_KEY está definida corretamente.
Conflitos de porta: Certifique-se de que a porta 9999 está livre.

A2A vs MCP: Semelhanças de Protocolo e Abordagem Unificada

Através desta implementação, descobrimos que A2A (Agent2Agent) e MCP (Model Context Protocol) compartilham semelhanças arquiteturais notáveis. Ambos os protocolos seguem um padrão similar para descoberta, troca de capacidades e execução.

Padrão de Implementação Unificado

Descoberta Principal: Tanto A2A quanto MCP seguem o mesmo padrão de implementação subjacente:

Comunicação baseada em HTTP: Ambos usam HTTP para comunicação (A2A usa APIs REST, MCP usa Server-Sent Events)
Design orientado por prompts: Ambos dependem de prompts LLM para decidir o que chamar e como chamar
Mecanismo de descoberta: Ambos fornecem maneiras de descobrir capacidades disponíveis
Respostas estruturadas: Ambos retornam dados estruturados que podem ser processados programaticamente

Observando a implementação mcp.py, podemos ver:

# Descoberta de ferramentas MCP via HTTP
async with sse_client(url) as (read, write):
    resources = await session.list_tools()
    
# Gerar prompt para tomada de decisão LLM
return template.render(tools=resources.tools)

# Executar chamada de ferramenta via HTTP
return await session.call_tool(tool_name, arguments=arguments)

Isto é conceitualmente idêntico ao padrão de chamada de agente A2A - descobrir capacidades, usar LLM para decidir o que chamar, então executar a chamada.

A2A como Interface Universal

Insight Principal: A2A pode servir como uma interface unificada tanto para comunicação agente-agente quanto para invocação de ferramentas, porque os padrões de chamada são essencialmente os mesmos:

A2A → Agente: Cliente → HTTP → Agente → Resposta LLM
A2A → Ferramenta: Cliente → HTTP → Wrapper de Ferramenta → Resposta de Ferramenta MCP

Ambos os padrões usam:

Comunicação HTTP
Descoberta de capacidades
Tomada de decisão orientada por LLM
Formato estruturado de solicitação/resposta

Benefícios desta Abordagem Unificada

Interface Única: Clientes precisam entender apenas um padrão de chamada
Interoperabilidade: Misturar agentes e ferramentas perfeitamente no mesmo fluxo de trabalho
Arquitetura Consistente: Mesmo padrão de implementação em diferentes tipos de capacidades
Design nativo para LLM: Ambos aproveitam o raciocínio LLM para seleção inteligente de capacidades

Isto demonstra que A2A e MCP não são protocolos concorrentes, mas padrões complementares que podem ser unificados sob um paradigma de interface única.

Arquitetura do Sistema e Fluxo

Abaixo está um diagrama de sequência detalhado mostrando o fluxo completo do protocolo A2A desde a entrada do cliente até a resposta final:

sequenceDiagram
    participant User
    participant Client as A2A Client
    participant LLM_Client as OpenRouter LLM (Client)
    participant Server as A2A Server
    participant AgentExecutor as Agent Executor
    participant Agent as Server Agent
    participant LLM_Server as OpenRouter LLM (Server)
    participant MCP as MCP Tool

    User->>Client: Entrada da pergunta: "O que é o protocolo A2A?"
    
    Note over Client: Inicializar Agente com agent_urls
    Client->>Server: GET /agent-card - Descobrir agentes disponíveis
    Server-->>Client: Retornar AgentCard com capacidades
    
    Note over Client: Renderizar template de prompt do agente
    Client->>LLM_Client: Enviar prompt de decisão com pergunta e agentes disponíveis
    LLM_Client-->>Client: Retornar JSON com agentes selecionados
    
    loop Para cada agente selecionado
        Client->>Server: POST /send-message-streaming
        
        Server->>AgentExecutor: execute(context, event_queue)
        AgentExecutor->>Agent: stream(query)
        
        Agent->>MCP: Obter ferramentas disponíveis
        MCP-->>Agent: Retornar definições de ferramentas
        
        Note over Agent: Renderizar template de prompt de ferramenta
        Agent->>LLM_Server: Enviar prompt de decisão com pergunta e ferramentas
        LLM_Server-->>Agent: Retornar JSON com ferramentas selecionadas
        
        loop Para cada ferramenta selecionada (máx. iterações)
            Agent->>MCP: Chamar ferramenta com argumentos
            MCP-->>Agent: Retornar resultado da ferramenta
            
            Note over Agent: Atualizar histórico called_tools
            Agent->>LLM_Server: Enviar prompt atualizado com resultados das ferramentas
            LLM_Server-->>Agent: Retornar próximas ferramentas ou resposta final
            
            alt Mais ferramentas necessárias
                Note over Agent: Continuar para próxima iteração
            else Tarefa completa
                Note over Agent: Tarefa concluída
            end
        end
        
        Agent-->>AgentExecutor: Produzir eventos de streaming
        AgentExecutor-->>Server: Encaminhar eventos para event_queue
        Server-->>Client: Transmitir chunks de resposta via HTTP
        
        Client->>Client: Extrair resposta das tags de resposta
        Note over Client: Adicionar à lista agent_answers
    end
    
    alt Necessita síntese final
        Client->>LLM_Client: Enviar prompt de síntese com todas as respostas
        LLM_Client-->>Client: Retornar resposta final sintetizada
    else Síntese não necessária
        Note over Client: Usar respostas existentes
    end
    
    Client-->>User: Transmitir resposta final com saídas dos agentes

Características Principais

Descoberta de Agentes: Descoberta automática de agentes disponíveis via protocolo A2A
Seleção Orientada por LLM: Seleção inteligente de agentes e ferramentas usando raciocínio LLM
Integração MCP: Integração perfeita com ferramentas MCP para recuperação de conhecimento
Pipeline de Streaming: Respostas de streaming em tempo real por todo o pipeline
Processamento Iterativo: Chamadas de ferramentas multi-iteração com contexto mantido

Descrição do Fluxo

O sistema segue estas fases principais:

Fase do Cliente: Usuário insere pergunta → Cliente descobre agentes → LLM seleciona agentes relevantes

Fase do Servidor: Servidor recebe solicitação → Agente descobre ferramentas → LLM seleciona ferramentas → Ferramentas executam iterativamente

Fase de Resposta: Resultados retornam pelo pipeline → Cliente sintetiza resposta final → Usuário recebe resposta

Esta arquitetura demonstra o poder do protocolo A2A na criação de agentes de IA interoperáveis que podem se descobrir e colaborar, enquanto aproveitam ferramentas MCP para acessar fontes de conhecimento externas.