Команда adk web завершается ошибкой ModuleNotFoundError или агент не отвечает в веб-интерфейсе — типичная ситуация при первом запуске Agent Development Kit от Google, и чаще всего причина кроется в неправильной структуре проекта или отсутствующем API-ключе. ADK — это открытый фреймворк для создания ИИ-агентов, который Google представил как инструмент для разработки, тестирования и развёртывания агентных систем на базе моделей Gemini и других LLM.
В этом руководстве разберём работу с ADK по шагам: от установки пакета до запуска многоагентной системы. Материал ориентирован на Python-версию фреймворка, так как именно она получила наибольшее распространение; для Java-версии часть шагов будет отличаться, и её стоит сверять с официальной документацией.
Что такое ADK и для каких задач он нужен
Agent Development Kit — это фреймворк с открытым исходным кодом, который позволяет описывать поведение агента в коде: какую модель использовать, какие инструменты подключить и как агенты взаимодействуют между собой. В отличие от простых обёрток над API, ADK даёт готовую инфраструктуру: сессии, память, оркестрацию и веб-интерфейс для отладки.
Типичные сценарии применения:
- 🤖 Создание чат-ботов с доступом к внешним инструментам — поиск, калькулятор, собственные функции.
- 🔗 Построение многоагентных систем, где один агент координирует работу других.
- 🧪 Прототипирование агентной логики с визуальной отладкой через встроенный веб-интерфейс.
- 🚀 Развёртывание агентов в облачной среде, например на Vertex AI.
Важно понимать: ADK — это инструмент для разработчиков, а не готовое приложение. Для работы потребуются базовые знания Python и доступ к API модели — например, ключ Google AI Studio или проект в Google Cloud.
Установка ADK и подготовка окружения
Перед установкой убедитесь, что у вас установлена поддерживаемая версия Python — актуальные требования указаны в официальной документации фреймворка, и они могут меняться от релиза к релизу. Настоятельно советуем работать в виртуальном окружении, чтобы зависимости ADK не конфликтовали с другими проектами.
python -m venv .venv
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
pip install google-adk
После установки проверьте, что пакет доступен: выполните pip show google-adk. Если команда возвращает информацию о версии — установка прошла успешно. Если pip сообщает, что пакет не найден, проверьте, активировано ли виртуальное окружение в текущем терминале: это самая частая причина «пропавшей» установки.
⚠️ Внимание: не устанавливайте ADK в глобальное окружение Python вместе с другими ML-библиотеками. Конфликты версий зависимостей — источник труднодиагностируемых ошибок при запуске агентов.
Далее потребуется ключ API. Для работы с моделями Gemini через Google AI Studio ключ создаётся в личном кабинете сервиса и передаётся через переменную окружения GOOGLE_API_KEY. Точное имя переменной и способ аутентификации зависят от выбранного бэкенда модели — сверяйтесь с документацией на момент настройки.
Создание первого агента
Структура проекта в ADK строгая: каждый агент — это отдельная папка с файлом agent.py, внутри которого определяется объект агента. Если назвать файл или переменную иначе, чем ожидает фреймворк, команда запуска не найдёт агента и выдаст ошибку загрузки.
Минимальный агент выглядит примерно так: вы импортируете класс Agent из пакета, указываете имя, модель и инструкцию — текст, описывающий роль и поведение агента. Инструкция (instruction) — главный рычаг управления поведением агента: именно она определяет, как он отвечает и когда вызывает инструменты.
from google.adk.agents import Agent
root_agent = Agent(
name="assistant",
model="gemini-2.0-flash",
instruction="Ты — помощник, отвечай кратко и по делу."
)
Обратите внимание: имя переменной root_agent и модель в примере приведены для иллюстрации — доступные идентификаторы моделей меняются, поэтому актуальное название берите из официальной документации или списка моделей вашего API-тарифа. Указание несуществующей модели приведёт к ошибке на этапе первого запроса агента.
Запуск и отладка через веб-интерфейс
Для локальной отладки ADK предоставляет встроенный веб-интерфейс. Он запускается командой из родительской директории проекта:
adk webПосле запуска в терминале появится локальный адрес — откройте его в браузере. В интерфейсе можно выбрать агента, отправлять сообщения и просматривать трассировку: какие вызовы инструментов выполнял агент, какие промпты уходили в модель и что вернулось в ответ. Это главный инструмент диагностики, когда агент ведёт себя не так, как ожидалось.
Если агент не появился в списке веб-интерфейса, проверьте три вещи: запущена ли команда из правильной директории, называется ли файл именно agent.py и нет ли синтаксических ошибок в коде — они выводятся в терминал при старте.
☑️ Проверка перед запуском агента
Подключение инструментов к агенту
Инструменты — это функции, которые агент может вызывать для выполнения действий: поиска информации, вычислений, обращения к внешним сервисам. В ADK обычная Python-функция становится инструментом, если передать её агенту в параметре tools. Модель получает описание функции и решает, когда её вызвать, основываясь на контексте диалога.
Чтобы модель корректно понимала назначение функции, пишите понятные docstring-описания и используйте аннотации типов для аргументов. Функция без документации или с неочевидными именами параметров часто вызывается моделью неправильно либо игнорируется вовсе.
- 🛠️ Давайте функциям говорящие имена:
get_weatherвместоfunc1. - 📝 Описывайте в docstring, что функция делает и что возвращает.
- 🔢 Аннотируйте типы аргументов и возвращаемого значения.
- ⚡ Держите функции быстрыми: долгий инструмент блокирует ответ агента.
⚠️ Внимание: инструменты выполняются с правами вашего Python-процесса. Не передавайте агенту функции, которые удаляют файлы или отправляют данные во внешние системы, без дополнительных проверок — модель может вызвать их в неподходящий момент.
Как модель решает, когда вызвать инструмент
При каждом запросе ADK передаёт модели описания всех доступных инструментов вместе с историей диалога. Модель может вернуть вместо текста специальный вызов функции — фреймворк выполняет её, а результат подставляет обратно в контекст, после чего модель формулирует финальный ответ пользователю. Этот цикл виден в трассировке веб-интерфейса.
Многоагентные системы и оркестрация
Одна из сильных сторон ADK — поддержка иерархий агентов. Вы можете создать координатора, который делегирует задачи специализированным суб-агентам: один отвечает за поиск, другой — за анализ данных, третий — за форматирование результата. Такое разделение упрощает инструкции каждого агента и делает систему предсказуемее.
При проектировании многоагентной системы начинайте с одного агента и добавляйте новых только тогда, когда инструкция стала слишком размытой или агент путается между задачами. Избыточное дробление на старте усложняет отладку: трассировка расползается по нескольким агентам, и найти источник ошибки становится труднее.
Типичные ошибки при работе с ADK
Большинство проблем на старте связано не с самим фреймворком, а с окружением и конфигурацией. Ниже — таблица частых симптомов и способов проверки.
| Симптом | Возможная причина | Что проверить |
|---|---|---|
| Агент не виден в adk web | Неверная структура папок или имя файла | Файл должен называться agent.py, команда запущена из родительской папки |
| Ошибка аутентификации | Не задан или недействителен API-ключ | Переменная окружения с ключом, срок действия ключа |
| ModuleNotFoundError | Пакет установлен в другое окружение | Активировано ли то же venv, куда ставился пакет |
| Модель не вызывает инструмент | Непонятное описание функции | Docstring, аннотации типов, имя функции |
| Ошибка «модель не найдена» | Устаревший или неверный идентификатор модели | Актуальный список моделей в документации API |
Если ни одна из проверок не помогла, смотрите полный текст ошибки в терминале: ADK выводит стектрейс Python, и последние строки обычно указывают на конкретный модуль или параметр, вызвавший сбой.
FAQ: частые вопросы о работе с ADK
Можно ли использовать ADK с моделями не от Google?
Да, фреймворк поддерживает подключение сторонних моделей через интеграции, однако набор поддерживаемых провайдеров и способ настройки зависят от версии пакета. Актуальный перечень смотрите в официальной документации ADK.
Нужен ли платный тариф для работы с ADK?
Сам фреймворк бесплатен и распространяется с открытым кодом. Затраты связаны с вызовами API модели: условия зависят от выбранного сервиса и тарифа, например от квот Google AI Studio или биллинга Google Cloud.
Чем ADK отличается от LangChain?
ADK ориентирован именно на агентные сценарии и предлагает встроенные средства оркестрации, сессий и веб-отладки из коробки, тогда как LangChain — более универсальный набор компонентов для работы с LLM. Выбор зависит от задачи: для быстрого прототипа агента ADK обычно требует меньше кода.
Можно ли развернуть агента ADK в продакшене?
Да, фреймворк предусматривает варианты развёртывания, включая облачные среды вроде Vertex AI. Конкретная процедура деплоя зависит от целевой платформы, поэтому перед публикацией изучите соответствующий раздел официальной документации и протестируйте агента под нагрузкой.
Где искать примеры кода для ADK?
Официальный репозиторий проекта и документация содержат примеры агентов разной сложности — от простого ассистента до многоагентных систем. Начинать лучше с минимального примера, постепенно добавляя инструменты и суб-агентов.