A2A Пример: Travel Planner OpenRouter

Это реализация на Python, которая соответствует протоколу A2A (Agent2Agent). Демонстрация туристического помощника, реализованная на основе официального a2a-python SDK от Google и OpenAI Python SDK. Это туристический помощник, соответствующий спецификациям модели OpenAI, способный предоставлять вам услуги планирования путешествий.

Исходный код

A2A Travel Planner OpenRouter

Архитектура проекта

Этот проект демонстрирует, как создать совместимого агента планирования путешествий с использованием протокола A2A, включая следующие основные компоненты:

• Travel Planner Agent: Основная логика туристического помощника на основе OpenAI-совместимого интерфейса
• Agent Executor: Адаптер протокола A2A, который связывает логику агента с сервером A2A
• A2A Server: Сервер, соответствующий протоколу A2A, предоставляющий стандартизированный интерфейс межагентного взаимодействия
• Loop Client: Тестовый клиент для взаимодействия с сервером A2A

Диаграмма последовательности рабочего процесса

sequenceDiagram
    participant Client
    participant A2AServer
    participant RequestHandler
    participant Executor as TravelPlannerAgentExecutor
    participant Agent as TravelPlannerAgent
    participant LLM as OpenAI-Compatible LLM

    Client->>A2AServer: Запрос карточки агента
    A2AServer->>Client: Возврат карточки агента (навыки, возможности)

    Note over Client,A2AServer: Пользователь запрашивает планирование путешествия

    Client->>A2AServer: message/sendStream (потоковый запрос)
    A2AServer->>RequestHandler: Маршрутизация потокового запроса
    RequestHandler->>Executor: execute(context, event_queue)
    
    Executor->>Agent: stream(query)
    Agent->>LLM: chat.completions.create(stream=True)
    
    loop Обработка потокового ответа
        LLM-->>Agent: Возврат фрагмента потокового содержимого
        Agent-->>Executor: yield {'content': chunk, 'done': False}
        Executor-->>RequestHandler: TaskArtifactUpdateEvent
        RequestHandler-->>A2AServer: Отправка SSE события
        A2AServer-->>Client: Обновление потокового содержимого
    end
    
    LLM-->>Agent: Финальный ответ завершен
    Agent-->>Executor: yield {'content': '', 'done': True}
    Executor-->>RequestHandler: Финальное TaskArtifactUpdateEvent
    RequestHandler-->>A2AServer: Финальное SSE событие
    A2AServer-->>Client: Потоковый ответ завершен

Основной рабочий процесс

1. Получение карточки агента: Клиент сначала получает карточку агента с сервера A2A для понимания возможностей и навыков агента
2. Обработка потокового запроса: Клиент отправляет потоковый запрос сообщения с пользовательским запросом
3. Выполнение агента: Исполнитель агента обрабатывает запрос и вызывает основную логику агента планирования путешествий
4. Взаимодействие с LLM: Агент ведет потоковую беседу с OpenAI-совместимой LLM
5. Ответ в реальном времени: Потоковая передача ответов клиенту в реальном времени через Server-Sent Events (SSE)

Начало работы

1. Настройте переменные окружения:

Скопируйте файл примера и настройте ваши API учетные данные.

cp env.example .env

Отредактируйте файл .env с вашими фактическими значениями:

# Обязательно: Ваш API ключ для сервиса AI модели
API_KEY=your_actual_api_key_here

# Опционально: Имя модели (по умолчанию: google/gemini-2.0-flash-001)
MODEL_NAME=google/gemini-2.0-flash-001

# Опционально: Базовый URL для API сервиса
BASE_URL=https://openrouter.ai/api/v1

2. Установите зависимости и запустите сервер:

   uv venv
   source .venv/bin/activate
   
   uv sync
   uv run .
   

3. Запустите клиент цикла в новом терминале:

   source .venv/bin/activate
   uv run loop_client.py
   

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

Приложение использует переменные окружения для конфигурации:

• API_KEY (обязательно): Ваш API ключ для сервиса AI модели
• MODEL_NAME (опционально): Имя модели для использования (по умолчанию: "google/gemini-2.0-flash-001")
• BASE_URL (опционально): Базовый URL для API сервиса (по умолчанию: "https://openrouter.ai/api/v1")

Технические особенности

Текущая реализация

• ✅ Соответствие протоколу A2A: Полное соответствие спецификации протокола Agent2Agent
• ✅ Потоковый ответ: Поддержка генерации потокового содержимого в реальном времени
• ✅ Совместимость с OpenAI: Поддержка любого OpenAI-совместимого API интерфейса
• ✅ Модульный дизайн: Четкое разделение между логикой агента и адаптацией протокола
• ✅ Конфигурация окружения: Гибкая конфигурация переменных окружения

Планы будущих улучшений

Улучшение управления состоянием задач

Основанное на примере Google A2A LangGraph, планируется добавить следующие функции:

• 🔄 Управление жизненным циклом задач: Реализация полного отслеживания состояния задач (отправлено → в работе → завершено/неудачно)
• 🔄 Поддержка многооборотной беседы: Добавление состояния input_required для поддержки сложных сценариев планирования путешествий, требующих уточнения пользователя
• 🔄 Постоянство задач: Реализация постоянства состояния задач для долгосрочных задач планирования
• 🔄 Улучшенная обработка ошибок: Более детальные состояния ошибок и механизмы восстановления
• 🔄 Отмена задач: Поддержка отмены выполняющихся задач

Пример управления состоянием

# Пример будущей реализации управления состоянием
class TravelPlannerTaskManager:
    async def handle_complex_query(self, query: str, context: RequestContext):
        # Определить, нужна ли дополнительная информация
        if self.needs_clarification(query):
            return TaskStatus(
                state=TaskState.input_required,
                message="Нужна дополнительная информация: Пожалуйста, укажите конкретное направление, даты и диапазон бюджета"
            )
        
        # Выполнить сложное многоэтапное планирование
        task_id = await self.create_long_running_task(query)
        return TaskStatus(
            state=TaskState.working,
            taskId=task_id,
            message="Создание детального плана путешествия..."
        )

Планируемые дополнения функций

• 📋 Поддержка структурированных данных: Добавление поддержки DataPart для сбора предпочтений путешествий на основе форм
• 🖼️ Поддержка мультимедиа: Поддержка FilePart для генерации и обработки изображений путешествий, карт и т.д.
• 🔍 Интеграция инструментов: Интеграция внешних API (погода, рейсы, отели и т.д.) как вызовы инструментов
• 🌐 Многоязычная поддержка: Расширение возможностей многоязычного планирования путешествий
• 📊 Аналитические метрики: Добавление сбора метрик времени выполнения задач, показателей успешности

Перейти к A2A