A2A Samples: Hello World Agent

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

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

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

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

• Python >= 3.10

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

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

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

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

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

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

• 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, включая:

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

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