Обзор проекта
Это простой пример агента 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']
Устранение неполадок
Общие проблемы
-
Порт занят
# Проверка использования порта lsof -i :9999 # Завершение занимающего процесса kill -9 <PID>
-
Ошибка установки зависимостей
# Очистка кэша и переустановка uv cache clean uv sync --reinstall
-
Несовместимость версии Python
# Проверка версии Python python --version # Убедитесь, что версия >= 3.10
Расширенная разработка
Добавление новых навыков
- Определите новый
AgentSkill
в__main__.py
- Измените логику обработки в
agent_executor.py
- Обновите конфигурацию карточки агента
Интеграция внешних API
- Добавьте новые зависимости в
pyproject.toml
- Реализуйте вызовы API в
agent_executor.py
- Обработайте асинхронные ответы и ошибки
Заключение
Этот пример Hello World демонстрирует базовое использование A2A SDK, включая:
- Создание и конфигурацию сервера агента
- Определение и управление навыками
- Клиент-серверную коммуникацию
- Аутентификацию и расширенную функциональность
Через этот пример вы можете быстро понять, как создавать свои собственные приложения интеллектуальных агентов.