A2A Protocol
A2A Samples: Hello World Agent

Обзор проекта

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

Описание версий зависимостей

Требования к версии Python

  • Python >= 3.10

Основные пакеты зависимостей

Название пакета Версия Назначение
a2a-sdk >= 0.2.5 Основной A2A SDK, предоставляет фреймворк агентов
uvicorn >= 0.34.2 ASGI сервер для запуска веб-приложений
click >= 8.1.8 Инструмент интерфейса командной строки
httpx >= 0.28.1 Асинхронный HTTP клиент
pydantic >= 2.11.4 Валидация и сериализация данных
python-dotenv >= 1.1.0 Управление переменными окружения
langchain-google-genai >= 2.1.4 Интеграция с Google Generative AI
langgraph >= 0.4.1 Фреймворк обработки языковых графов

Структура проекта

helloworld/
├── __init__.py              # Файл инициализации пакета
├── __main__.py              # Точка входа основной программы
├── agent_executor.py        # Реализация исполнителя агента
├── test_client.py           # Тестовый клиент
├── pyproject.toml           # Конфигурация проекта и зависимости
├── uv.lock                  # Файл блокировки зависимостей
└── README.md                # Документация проекта

Настройка окружения

1. Установка менеджера пакетов UV

Если вы еще не установили UV, сначала установите его:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# или используйте pip
pip install uv

2. Клонирование проекта

git clone https://github.com/google-a2a/a2a-samples.git
cd a2a-samples/samples/python/agents/helloworld

3. Установка зависимостей

UV автоматически установит все зависимости согласно файлам pyproject.toml и uv.lock:

uv sync

Описание архитектуры кода

Основные компоненты

1. HelloWorldAgent (agent_executor.py)

class HelloWorldAgent:
    """Hello World Agent."""
    
    async def invoke(self) -> str:
        return 'Hello World'

2. HelloWorldAgentExecutor (agent_executor.py)

class HelloWorldAgentExecutor(AgentExecutor):
    """Реализация исполнителя агента"""
    
    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
        result = await self.agent.invoke()
        event_queue.enqueue_event(new_agent_text_message(result))

3. Конфигурация сервера (__main__.py)

  • Определение навыков агента (AgentSkill)
  • Настройка публичных и расширенных карточек агента (AgentCard)
  • Настройка обработчиков запросов и хранилища задач
  • Запуск сервера Uvicorn

Шаги запуска

1. Запуск сервера агента

uv run .

Сервер запустится на http://localhost:9999.

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

В другом окне терминала:

uv run test_client.py

3. Проверка сервиса

Вы можете проверить, что сервис работает правильно, следующими способами:

Доступ к информации карточки агента

curl http://localhost:9999/.well-known/agent.json

Доступ к расширенной карточке агента (требуется аутентификация)

curl -H "Authorization: Bearer dummy-token-for-extended-card" \
     http://localhost:9999/agent/authenticatedExtendedCard

Диаграмма потока проекта

Поток взаимодействия A2A клиента и сервера

sequenceDiagram
    participant Client as A2A Client
    participant Server as A2A Server
    participant Agent as HelloWorldAgent
    participant Queue as EventQueue
    
    Note over Client,Server: 1. Фаза обнаружения сервиса
    Client->>Server: GET /.well-known/agent.json
    Server-->>Client: Возврат публичной карточки агента
    
    Note over Client,Server: 2. Получение расширенной карточки (опционально)
    Client->>Server: GET /agent/authenticatedExtendedCard<br/>(with Bearer token)
    Server-->>Client: Возврат расширенной карточки агента
    
    Note over Client,Server: 3. Поток отправки сообщений
    Client->>Server: POST /agent/message<br/>{"message": {"role": "user", "parts": [...]}}
    
    Note over Server,Queue: 4. Внутренняя обработка сервера
    Server->>Agent: Вызов HelloWorldAgentExecutor.execute()
    Agent->>Agent: Выполнение HelloWorldAgent.invoke()
    Agent-->>Queue: Генерация сообщения "Hello World"
    Queue-->>Server: Возврат результата очереди событий
    
    Note over Client,Server: 5. Возврат ответа
    Server-->>Client: Возврат ответа сообщения
    
    Note over Client,Server: 6. Потоковая обработка сообщений (опционально)
    Client->>Server: POST /agent/message/stream
    Server-->>Client: Потоковый возврат блоков сообщений
    Server-->>Client: Блок сообщения 1
    Server-->>Client: Блок сообщения 2
    Server-->>Client: Маркер окончания

Диаграмма потока системной архитектуры

graph TB
    subgraph "Клиентское окружение"
        C1[Запуск тестового клиента]
        C2[A2ACardResolver<br/>Парсинг карточки агента]
        C3[A2AClient<br/>Инициализация]
        C4[Отправка запроса сообщения]
        C5[Обработка ответа]
    end
    
    subgraph "Сетевая коммуникация"
        N1[HTTP/HTTPS запрос]
        N2[Передача данных JSON]
    end
    
    subgraph "Серверное окружение"
        S1[A2AStarletteApplication<br/>Веб-сервер]
        S2[DefaultRequestHandler<br/>Обработчик запросов]
        S3[HelloWorldAgentExecutor<br/>Исполнитель агента]
        S4[HelloWorldAgent<br/>Основная логика агента]
        S5[InMemoryTaskStore<br/>Хранилище задач]
        S6[EventQueue<br/>Очередь событий]
    end
    
    subgraph "Конфигурация агента"
        A1[Публичная карточка агента<br/>Базовые навыки]
        A2[Расширенная карточка агента<br/>Улучшенные навыки]
    end
    
    %% Поток клиента
    C1 --> C2
    C2 --> C3
    C3 --> C4
    C4 --> C5
    
    %% Сетевая коммуникация
    C4 --> N1
    N1 --> N2
    N2 --> S1
    S1 --> N2
    N2 --> C5
    
    %% Поток сервера
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S6
    S6 --> S3
    S3 --> S2
    S2 --> S1
    
    %% Связь конфигурации
    A1 --> S1
    A2 --> S1
    S2 --> S5
    
    %% Стилизация
    style C3 fill:#e3f2fd
    style S1 fill:#f3e5f5
    style S4 fill:#e8f5e8
    style N2 fill:#fff3e0

API Endpoints

Публичные endpoints

Endpoint Метод Описание
/.well-known/agent.json GET Получение информации публичной карточки агента
/agent/message POST Отправка сообщения агенту
/agent/message/stream POST Потоковая отправка сообщений

Endpoints аутентификации

Endpoint Метод Описание Аутентификация
/agent/authenticatedExtendedCard GET Получение расширенной карточки агента Bearer Token

Конфигурация навыков

Базовые навыки

  • ID: hello_world
  • Название: Returns hello world
  • Описание: just returns hello world
  • Примеры: ['hi', 'hello world']

Расширенные навыки (требуется аутентификация)

  • ID: super_hello_world
  • Название: Returns a SUPER Hello World
  • Описание: A more enthusiastic greeting, only for authenticated users
  • Примеры: ['super hi', 'give me a super hello']

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

Общие проблемы

  1. Порт занят

    # Проверка использования порта
    lsof -i :9999
    # Завершение занимающего процесса
    kill -9 <PID>
    
  2. Ошибка установки зависимостей

    # Очистка кэша и переустановка
    uv cache clean
    uv sync --reinstall
    
  3. Несовместимость версии Python

    # Проверка версии Python
    python --version
    # Убедитесь, что версия >= 3.10
    

Расширенная разработка

Добавление новых навыков

  1. Определите новый AgentSkill в __main__.py
  2. Измените логику обработки в agent_executor.py
  3. Обновите конфигурацию карточки агента

Интеграция внешних API

  1. Добавьте новые зависимости в pyproject.toml
  2. Реализуйте вызовы API в agent_executor.py
  3. Обработайте асинхронные ответы и ошибки

Заключение

Этот пример Hello World демонстрирует базовое использование A2A SDK, включая:

  • Создание и конфигурацию сервера агента
  • Определение и управление навыками
  • Клиент-серверную коммуникацию
  • Аутентификацию и расширенную функциональность

Через этот пример вы можете быстро понять, как создавать свои собственные приложения интеллектуальных агентов.