A2A Python Пример: GitHub Агент

Интеллектуальный GitHub агент, построенный с помощью A2A (Agent2Agent) SDK, который может запрашивать GitHub репозитории, последние обновления, коммиты и активность проектов, используя естественный язык.

🏗️ Архитектура

Этот проект реализует A2A сервер, который использует агента на основе OpenAI с интеграцией GitHub API. Архитектура состоит из следующих ключевых компонентов:

Обзор компонентов

A2A Сервер (__main__.py): Основное серверное приложение, которое обрабатывает HTTP запросы и управляет жизненным циклом агента
Исполнитель OpenAI Агента (openai_agent_executor.py): Выполняет задачи агента с интеграцией OpenRouter API
Набор инструментов GitHub (github_toolset.py): Предоставляет инструменты GitHub API для операций с репозиториями
Определение агента (openai_agent.py): Определяет возможности агента и системный промпт

Поток архитектуры

sequenceDiagram
    participant Client as A2A Клиент
    participant Server as A2A Сервер
    participant Agent as OpenAI Агент
    participant GitHub as GitHub API
    participant OpenRouter as OpenRouter API

    Note over Client,OpenRouter: Архитектура A2A GitHub Агента

    Client->>Server: HTTP Запрос<br/>(запрос о GitHub)
    Server->>Agent: Обработка запроса<br/>(OpenAIAgentExecutor)
    
    Agent->>OpenRouter: Отправка завершения чата<br/>(с определенными инструментами)
    OpenRouter-->>Agent: Ответ с вызовами инструментов

    loop Выполнение инструментов
        Agent->>GitHub: API Вызов<br/>(GitHubToolset)
        GitHub-->>Agent: Данные репозитория/коммитов
        Agent->>OpenRouter: Отправка результатов инструментов
        OpenRouter-->>Agent: Финальный ответ
    end

    Agent->>Server: Потоковый ответ<br/>(TaskUpdater)
    Server->>Client: HTTP Ответ<br/>(отформатированные результаты)

    Note over Client: Пользователь видит данные GitHub<br/>отформатированные ИИ

🔧 Логика ключевых модулей

1. Основной сервер (`main.py`)

Инициализирует A2A сервер с фреймворком Starlette
Создает AgentCard, который определяет возможности и навыки агента
Настраивает исполнитель OpenAI агента с инструментами GitHub
Запускает HTTP сервер на указанном хосте и порту

2. Набор инструментов GitHub (`github_toolset.py`)

Предоставляет три основные функции GitHub API:

get_user_repositories(): Получает последние репозитории пользователя
get_recent_commits(): Извлекает последние коммиты для конкретного репозитория
search_repositories(): Ищет репозитории с недавней активностью

Все функции включают обработку ошибок и поддерживают дополнительные параметры для фильтрации.

3. Исполнитель OpenAI агента (`openai_agent_executor.py`)

Управляет потоком разговора с OpenRouter API
Преобразует инструменты GitHub в формат вызова функций OpenAI
Обрабатывает выполнение инструментов и потоковые ответы
Реализует итеративный разговор с вызовами инструментов

4. Определение агента (`openai_agent.py`)

Создает агента с системным промптом и доступными инструментами
Определяет поведение агента для запросов, связанных с GitHub
Настраивает агента для предоставления полезной информации о репозиториях

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

Python 3.10 или выше
UV - Менеджер пакетов Python
Ключ API OpenRouter - Для возможностей ИИ
Персональный токен доступа GitHub (необязательно, но рекомендуется для более высоких лимитов скорости)

🚀 Пошаговая настройка и запуск

Шаг 1: Клонирование и настройка окружения

# Клонировать репозиторий
git clone https://github.com/sing1ee/a2a-py-github-agent.git
cd a2a-py-github-agent

# Создать виртуальное окружение
uv venv
source .venv/bin/activate  # На Windows: .venv\Scripts\activate

Шаг 2: Установка зависимостей

# Установить зависимости с помощью UV
uv sync

Шаг 3: Настройка переменных окружения

Создайте файл .env в корне проекта:

# Ключ API OpenRouter (обязательно)
echo "OPENROUTER_API_KEY=your_openrouter_api_key_here" > .env

# Персональный токен доступа GitHub (необязательно, но рекомендуется)
echo "GITHUB_TOKEN=your_github_personal_access_token_here" >> .env

Примечание: Токен GitHub необязателен. Без него агент будет использовать неаутентифицированный доступ с ограниченными лимитами скорости (60 запросов в час против 5000 с токеном).

Шаг 4: Запуск A2A сервера

# Активировать виртуальное окружение
source .venv/bin/activate

# Запустить сервер
uv run .

Сервер запустится на http://localhost:10007 по умолчанию.

🧪 Тестирование клиента

Вариант 1: Использование клиента A2A Movie Agent

Вы можете протестировать GitHub агента, используя клиент A2A Movie Agent:

# Клонировать клиент A2A Movie Agent
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# Установить зависимости
bun install

# Подключиться к вашему GitHub агенту
bun cli http://localhost:10007

Это запустит интерактивный CLI, который подключается к вашему серверу GitHub агента.

Вариант 2: Использование прямых HTTP запросов

Вы также можете тестировать с помощью curl или любого HTTP клиента:

# Пример: Тест с простым запросом
curl -X POST http://localhost:10007/ \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Показать последние коммиты для репозитория 'facebook/react'"
        }
      ],
      "messageId": "9229e770-767c-417b-a0b0-f0741243c589"
    },
    "metadata": {}
  }
}'

💡 Примеры запросов

GitHub агент может обрабатывать запросы типа:

Последние коммиты: "Показать последние коммиты для репозитория 'facebook/react'"
Поиск репозиториев: "Найти популярные Python репозитории с недавней активностью"
Активность проекта: "Какие последние обновления в репозиториях машинного обучения?"

🔑 Настройка токена GitHub

Чтобы создать персональный токен доступа GitHub для лучших лимитов скорости:

Перейдите в Настройки GitHub > Токены
Нажмите "Сгенерировать новый токен (классический)"
Выберите следующие области:
- repo - Доступ к репозиториям
- user - Доступ к информации пользователя
Скопируйте токен и добавьте его в ваш файл .env

🛠️ Параметры конфигурации

Конфигурация сервера

Вы можете настроить сервер, используя параметры командной строки:

# Пользовательский хост и порт
uv run . --host=0.0.0.0 --port=10007

Переменные окружения

OPENROUTER_API_KEY: Ваш ключ API OpenRouter (обязательно)
GITHUB_TOKEN: Персональный токен доступа GitHub (необязательно)

📖 Документация API

Доступные инструменты

get_user_repositories
- Получить репозитории пользователя с недавними обновлениями
- Параметры: username (необязательно), days (по умолчанию: 30), limit (по умолчанию: 10)
get_recent_commits
- Получить последние коммиты для репозитория
- Параметры: repo_name (обязательно), days (по умолчанию: 7), limit (по умолчанию: 10)
search_repositories
- Поиск репозиториев с недавней активностью
- Параметры: query (обязательно), sort (по умолчанию: 'updated'), limit (по умолчанию: 10)

📄 Лицензия

Этот проект лицензирован под лицензией MIT - см. файл LICENSE для подробностей.

🔗 Связанные проекты

A2A SDK - Базовая реализация протокола A2A
A2A Movie Agent - Агент информации о фильмах, построенный с протоколом A2A