Интеграция A2A MCP

Git Репозиторий：A2A MCP

Этот репозиторий демонстрирует, как настроить и использовать a2a-python SDK для создания простого сервера и клиента, реализующих протокол a2a, где агент-сервер реализован через mcp.

Обзор

A2A (Agent2Agent): Протокол и SDK для создания совместимых ИИ-агентов.
Этот пример: Показывает, как запустить базовый A2A сервер и клиент, обмениваться сообщениями и просматривать ответы.

Предварительные требования

Python 3.13+
uv (для быстрого управления зависимостями и запуска)
API ключ для OpenRouter (установить как OPENROUTER_API_KEY)

Установка

Клонировать репозиторий:

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

Установить зависимости:
```
uv venv
source .venv/bin/activate
```
Установить переменные окружения:
```
export OPENROUTER_API_KEY=your-openrouter-api-key
```
Или создать файл .env с содержимым:
```
OPENROUTER_API_KEY=your-openrouter-api-key
```
Примечание: Вы можете получить свой API ключ OpenRouter на https://openrouter.ai/

Запуск примера

1. Запуск сервера

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

Сервер запустится на порту 9999.

Проверка карточки агента:

валидатор протокола a2a
Руководство: Как проверить карточку вашего агента

2. Запуск клиента

В новом терминале:

uv venv
source .venv/bin/activate
uv run --env-file .env a2a-client --question "Что такое протокол A2A?"

Клиент подключится к серверу и отправит запрос.

3. Просмотр ответа

Ответ от клиента будет сохранен в response.xml.

Конфигурация

Система использует следующую конфигурацию:

Модель: google/gemini-flash-1.5 через OpenRouter
Базовый URL: https://openrouter.ai/api/v1

Структура файлов

src/a2a_mcp_openrouter/server/: Реализация сервера.
src/a2a_mcp_openrouter/client/: Реализация клиента.
response.xml: Пример ответа от клиента.

Устранение неполадок

Отсутствующие зависимости: Убедитесь, что у вас установлен uv.
Ошибки API ключа: Убедитесь, что OPENROUTER_API_KEY установлен правильно.
Конфликты портов: Убедитесь, что порт 9999 свободен.

A2A против MCP: Сходства протоколов и единый подход

Через эту реализацию мы обнаружили, что A2A (Agent2Agent) и MCP (Model Context Protocol) имеют замечательные архитектурные сходства. Оба протокола следуют схожему паттерну для обнаружения, обмена возможностями и выполнения.

Единый паттерн реализации

Ключевое открытие: И A2A, и MCP следуют одному и тому же базовому паттерну реализации:

HTTP-основанная коммуникация: Оба используют HTTP для связи (A2A использует REST API, MCP использует Server-Sent Events)
Дизайн на основе промптов: Оба полагаются на промпты LLM для принятия решений о том, что вызывать и как это вызывать
Механизм обнаружения: Оба предоставляют способы обнаружения доступных возможностей
Структурированные ответы: Оба возвращают структурированные данные, которые могут быть обработаны программно

Глядя на реализацию mcp.py, мы можем видеть:

# Обнаружение инструментов MCP через HTTP
async with sse_client(url) as (read, write):
    resources = await session.list_tools()
    
# Генерация промпта для принятия решений LLM
return template.render(tools=resources.tools)

# Выполнение вызова инструмента через HTTP
return await session.call_tool(tool_name, arguments=arguments)

Это концептуально идентично паттерну вызова агента A2A - обнаружить возможности, использовать LLM для принятия решения о том, что вызывать, затем выполнить вызов.

A2A как универсальный интерфейс

Ключевое понимание: A2A может служить единым интерфейсом как для связи агент-агент, так и для вызова инструментов, поскольку паттерны вызовов по сути одинаковы:

A2A → Агент: Клиент → HTTP → Агент → Ответ LLM
A2A → Инструмент: Клиент → HTTP → Обертка инструмента → Ответ инструмента MCP

Оба паттерна используют:

HTTP коммуникацию
Обнаружение возможностей
Принятие решений на основе LLM
Структурированный формат запрос/ответ

Преимущества этого единого подхода

Единый интерфейс: Клиентам нужно понимать только один паттерн вызовов
Совместимость: Беспрепятственное смешивание агентов и инструментов в одном рабочем процессе
Согласованная архитектура: Один и тот же паттерн реализации для разных типов возможностей
LLM-нативный дизайн: Оба используют рассуждения LLM для интеллектуального выбора возможностей

Это демонстрирует, что A2A и MCP не являются конкурирующими протоколами, а дополняющими паттернами, которые могут быть объединены под единой парадигмой интерфейса.

Архитектура системы и поток

Ниже представлена подробная диаграмма последовательности, показывающая полный поток протокола A2A от ввода клиента до финального ответа:

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: Ввод вопроса: "Что такое протокол A2A?"
    
    Note over Client: Инициализация агента с agent_urls
    Client->>Server: GET /agent-card - Обнаружение доступных агентов
    Server-->>Client: Возврат AgentCard с возможностями
    
    Note over Client: Рендеринг шаблона промпта агента
    Client->>LLM_Client: Отправка промпта решения с вопросом и доступными агентами
    LLM_Client-->>Client: Возврат JSON с выбранными агентами
    
    loop Для каждого выбранного агента
        Client->>Server: POST /send-message-streaming
        
        Server->>AgentExecutor: execute(context, event_queue)
        AgentExecutor->>Agent: stream(query)
        
        Agent->>MCP: Получение доступных инструментов
        MCP-->>Agent: Возврат определений инструментов
        
        Note over Agent: Рендеринг шаблона промпта инструмента
        Agent->>LLM_Server: Отправка промпта решения с вопросом и инструментами
        LLM_Server-->>Agent: Возврат JSON с выбранными инструментами
        
        loop Для каждого выбранного инструмента (макс. итераций)
            Agent->>MCP: Вызов инструмента с аргументами
            MCP-->>Agent: Возврат результата инструмента
            
            Note over Agent: Обновление истории called_tools
            Agent->>LLM_Server: Отправка обновленного промпта с результатами инструментов
            LLM_Server-->>Agent: Возврат следующих инструментов или финального ответа
            
            alt Нужны дополнительные инструменты
                Note over Agent: Продолжение к следующей итерации
            else Задача выполнена
                Note over Agent: Задача завершена
            end
        end
        
        Agent-->>AgentExecutor: Передача потоковых событий
        AgentExecutor-->>Server: Пересылка событий в event_queue
        Server-->>Client: Потоковая передача фрагментов ответа через HTTP
        
        Client->>Client: Извлечение ответа из тегов ответа
        Note over Client: Добавление в список agent_answers
    end
    
    alt Нужен финальный синтез
        Client->>LLM_Client: Отправка промпта синтеза со всеми ответами
        LLM_Client-->>Client: Возврат финального синтезированного ответа
    else Синтез не нужен
        Note over Client: Использование существующих ответов
    end
    
    Client-->>User: Потоковая передача финального ответа с выводами агентов

Ключевые особенности

Обнаружение агентов: Автоматическое обнаружение доступных агентов через протокол A2A
Выбор на основе LLM: Интеллектуальный выбор агентов и инструментов с использованием рассуждений LLM
Интеграция MCP: Беспрепятственная интеграция с инструментами MCP для получения знаний
Потоковый конвейер: Потоковые ответы в реальном времени по всему конвейеру
Итеративная обработка: Многоитерационные вызовы инструментов с сохранением контекста

Описание потока

Система следует этим основным фазам:

Фаза клиента: Пользователь вводит вопрос → Клиент обнаруживает агентов → LLM выбирает релевантных агентов

Фаза сервера: Сервер получает запрос → Агент обнаруживает инструменты → LLM выбирает инструменты → Инструменты выполняются итеративно

Фаза ответа: Результаты передаются обратно по конвейеру → Клиент синтезирует финальный ответ → Пользователь получает ответ

Эта архитектура демонстрирует мощь протокола A2A в создании совместимых ИИ-агентов, которые могут обнаруживать друг друга и сотрудничать, используя инструменты MCP для доступа к внешним источникам знаний.