Создание ИИ-агентов с помощью ADK: основы

1. Обзор

ИИ-агент сочетает большую языковую модель (LLM) с инструкциями, состоянием и инструментами, чтобы анализировать запросы пользователей и автономно выполнять многоэтапные задачи. Без структурированной платформы агентов разработчикам приходится вручную подключать клиентов модели, конфигурацию среды, сеансы разговоров и локальные интерфейсы отладки, прежде чем тестировать хотя бы одну подсказку.

В первой части серии Создание ИИ-агентов с помощью ADK вы настроите среду разработки Python в Google Cloud и создадите шаблон агента personal_assistant на платформе агентов с помощью Agent Development Kit (ADK 2) и gemini-3.8-flash. Вы изучите сгенерированный пакет агента и протестируете агент с помощью интерактивного интерфейса командной строки терминала (adk run) и браузерного веб-интерфейса ADK (adk web). Вы также можете открыть эту практическую работу напрямую по ссылке goo.gle/adk-foundation.

Требования

Что вы узнаете

  • Как настроить Google Cloud Shell и изолированную среду Python 3.12 с помощью uv.
  • Как создать базовый пакет агента ADK 2 на основе gemini-3.8-flash на платформе Agent Platform
  • Как ADK 2 организует код агента в файлах agent.py, __init__.py и .env.
  • Как запускать, тестировать и проверять события, трассировки и сеансы с поддержкой SQLite в adk run и adk web

Что вам потребуется

  • Аккаунт Google (если вы хотите получить бонусы за участие в семинаре, используйте личный аккаунт @gmail.com).
  • ссылка на бонус от преподавателя (и камера телефона, чтобы отсканировать QR-код) или активный платежный аккаунт Cloud.
  • Google Chrome (рекомендуется использовать окно инкогнито, чтобы не путать личный и рабочий аккаунты).

2. Как получить бонусы Google Cloud (необязательно)

Если вы посещаете семинар, на котором предоставляется ссылка на бонус, воспользуйтесь бонусом Google Developer Program, чтобы создать платежный аккаунт без кредитной карты.

Получите бонус на рекламу

  1. Откройте ссылку на бонусы в окне инкогнито и войдите в аккаунт @gmail.com.
  2. На странице Claim Your Benefit (Получить бонус) нажмите Claim Credit (Получить бонус).

Карточка "Получите бонус" в Google Builders Hub с кнопкой "Получить бонус"

  1. Если вам будет предложено создать профиль Google Developer Program, заполните форму.
  2. Когда появится сообщение Отсканируйте, чтобы подтвердить, что вы человек, отсканируйте QR-код с помощью телефона и пройдите проверку. Если QR-код не появился, обновите страницу и снова нажмите Получить бонус.

Диалоговое окно с QR-кодом для подтверждения того, что вы человек, в Google Developer Program

  1. Дождитесь сообщения Бонус за участие в мероприятии успешно активирован и нажмите Открыть платежный аккаунт.

Google Builders Hub с сообщением об успешном получении бонуса и кнопкой "Открыть платежный аккаунт"

🔍 Проверьте свою работу

Настройка платежного аккаунта занимает до 3 минут.

  1. Откройте Google Cloud Billing (или скопируйте URL в окно инкогнито) и выберите Your billing accounts (Ваши платежные аккаунты).
https://console.cloud.google.com/billing
  1. Обновляйте страницу, пока у аккаунта GDP Credit не появится статус Активно.

Страница управления платежным аккаунтом Google Cloud, на которой показан активный платежный аккаунт GDP Credit

3. Создайте проект Google Cloud (необязательно)

Создайте отдельный проект Google Cloud, чтобы все ресурсы из этой практической работы были изолированы и их можно было легко удалить.

  1. Откройте страницу Создание проекта или скопируйте URL в окно инкогнито.
https://console.cloud.google.com/projectcreate
  1. Укажите сведения о проекте:
    • Название проекта, например google-cloud-workshop.
    • Платежный аккаунт (если показан): выберите GDP Credit (или ваш активный платежный аккаунт).
    • Родительский ресурс: Без организации (или ваша организация, если требуется).
  2. Запишите сгенерированный идентификатор проекта, который указан под названием проекта, и нажмите Создать.

Экран создания проекта Google Cloud с полями "Название проекта", "Идентификатор проекта", "Родительский ресурс" и кнопкой "Создать"

🔍 Проверьте свою работу

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

Меню уведомлений в консоли Google Cloud, в котором показаны ссылки "Создать проект" и "Выбрать проект"

4. Как настроить среду

Настройте Google Cloud Shell, включите Agent Platform API и создайте изолированную виртуальную среду Python 3.12 с помощью uv.

Как настроить Cloud Shell

  1. Нажмите Activate Cloud Shell (Активировать Cloud Shell) (>_) на панели инструментов консоли Google Cloud или откройте Google Cloud Shell напрямую (или скопируйте URL в окно инкогнито):
https://shell.cloud.google.com/?show=ide,terminal

Кнопка "Активировать Cloud Shell" на панели инструментов консоли Google Cloud

  1. При необходимости нажмите Авторизовать.

Диалоговое окно авторизации Cloud Shell

  1. Выберите активный идентификатор проекта Google Cloud в нумерованном меню терминала.
unset CLOUDSDK_CORE_PROJECT
PS3="Select your project (e.g. 1): "
select PROJECT_ID in $(gcloud projects list --format="value(projectId)"); do
  [ -n "$PROJECT_ID" ] && gcloud config set project "$PROJECT_ID" && break
done

Вы должны увидеть примерно такой результат (для проектов без тегов также выводится информационная строка [environment: untagged]):

1) google-cloud-workshop-4210
2) my-cloud-project-8812
Select your project (e.g. 1): 1
Updated property [core/project].

Убедитесь, что выбранный идентификатор проекта выделен желтым цветом в командной строке Cloud Shell:

Терминал Cloud Shell с выделенным желтым цветом идентификатором проекта

Включите необходимые API

Включите Agent Platform API, чтобы агент ADK мог вызывать модели Gemini.

gcloud services enable aiplatform.googleapis.com

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

Operation "operations/acat.p2-..." finished successfully.

Как создать виртуальную среду Python и установить ADK

Создайте каталог рабочей области ~/ai-agents-adk и активируйте виртуальную среду Python 3.12:

cd ~
mkdir -p ai-agents-adk && cd ~/ai-agents-adk

which uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

uv venv .venv --python 3.12
source .venv/bin/activate

Убедитесь, что в начале командной строки терминала появился префикс (.venv):

Терминал Cloud Shell с префиксом .venv в активной виртуальной среде Python

Установите ADK в активной виртуальной среде:

uv pip install --no-cache "google-adk==2.14.0"

🔍 Проверьте свою работу

Проверьте установленную версию CLI adk:

adk --version

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

adk, version 2.14.0

5. Создайте каркас агента

Сгенерируйте начальный пакет агента personal_assistant с помощью adk create. ADK создает четыре файла в папке personal_assistant/:

  • agent.py: определяет root_agent с его моделью, названием, описанием и системной инструкцией.
  • __init__.py: помечает personal_assistant как пакет Python, чтобы ADK мог найти и импортировать agent.py.
  • .env: хранит флаг серверной части (GOOGLE_GENAI_USE_ENTERPRISE=1), идентификатор проекта и местоположение (global).
  • .gitignore – исключает .env и локальные файлы сеансов SQLite .adk/ из системы управления версиями.

Запуск по расписанию: adk create

Создайте пакет personal_assistant из ~/ai-agents-adk:

cd ~/ai-agents-adk
adk create personal_assistant

При появлении запроса выберите следующие параметры (если при первом запуске появится запрос Enable telemetry? [Y/n]:, нажмите Ввод или введите n и нажмите Ввод):

  1. Выберите модель для корневого агента. Введите 2, чтобы выбрать gemini-3.8-flash (вариант 1 выбирает gemini-3.5-flash), и нажмите Ввод.
  2. Выберите серверную часть. Введите 2, чтобы выбрать серверную часть Google Cloud Agent Platform (вариант 2 в меню CLI ниже), и нажмите Ввод.
  3. Введите идентификатор проекта Google Cloud. Нажмите Ввод, чтобы принять идентификатор проекта, указанный в скобках, или введите другой идентификатор.
  4. Enter Google Cloud region (Укажите регион Google Cloud). Введите global (требуется для работы gemini-3.8-flash на Agent Platform) и нажмите Ввод.

🔍 Проверьте свою работу

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

Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2
1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [google-cloud-workshop-4210]:
Enter Google Cloud region [us-central1]: global

Agent created in /home/your_username/ai-agents-adk/personal_assistant:
- .env
- .gitignore
- __init__.py
- agent.py

⚠️  WARNING: Secrets (like GOOGLE_API_KEY) are stored in .env.

Next steps:
- Chat with your agent in the terminal: adk run personal_assistant
- Or in the browser: adk web .
- Have your coding agent evaluate and deploy it: uvx google-agents-cli setup
  (other install options: https://adk.dev/get-started/agents-cli/)

6. Изучите сгенерированный код

Откройте ~/ai-agents-adk в редакторе Cloud Shell, чтобы просматривать сгенерированные файлы рядом с терминалом:

which cloudshell >/dev/null 2>&1 && cloudshell workspace ~/ai-agents-adk || true

Повторно активируйте виртуальную среду в перезагруженном терминале:

cd ~/ai-agents-adk
source .venv/bin/activate

Вы также можете открыть рабочую область вручную в редакторе Cloud Shell, нажав на значок проводника (или Файл > Открыть папку…) и выбрав ai-agents-adk:

Панель проводника в редакторе Cloud Shell с кнопкой "Открыть папку"

Файлы, названия которых начинаются с точки, например .env, по умолчанию скрыты в дереве Проводника. В строке меню сверху нажмите Вид > Показать скрытые файлы, чтобы увидеть файл personal_assistant/.env.

Меню "Вид" в редакторе Cloud Shell с выделенным пунктом "Показать/скрыть скрытые файлы"

Просмотр: agent.py

Откройте файл ~/ai-agents-adk/personal_assistant/agent.py в редакторе Cloud Shell:

cloudshell edit ~/ai-agents-adk/personal_assistant/agent.py

Проверьте созданный файл (изменения не требуются):

from google.adk.agents.llm_agent import Agent

root_agent = Agent(
    model='gemini-3.8-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)
  • from google.adk.agents.llm_agent import Agent – импортирует класс Agent ADK (псевдоним LlmAgent; ADK 2 также предоставляет from google.adk import Agent в качестве сокращения верхнего уровня при написании пользовательского кода).
  • model='gemini-3.8-flash' – выбирает gemini-3.8-flash в качестве модели, которая будет отвечать на запросы.
  • name='root_agent': назначает идентификатор, который ADK использует в журналах, трассировках и графах с несколькими агентами.
  • description='...': краткое описание того, что делает агент, когда родительский координатор решает, делегировать ли ему задачу.
  • instruction='...' – задает системный запрос, определяющий тон и поведение агента.

Изучите __init__.py и .env.

Откройте personal_assistant/__init__.py, чтобы убедиться, что он повторно экспортирует agent, чтобы adk run и adk web могли обнаружить root_agent:

from . import agent as agent

Откройте personal_assistant/.env, чтобы проверить конфигурацию среды выполнения:

GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=google-cloud-workshop-4210
GOOGLE_CLOUD_LOCATION=global
  • GOOGLE_GENAI_USE_ENTERPRISE=1 – вызовы модели ADK направляются через платформу агентов с использованием ваших учетных данных Google Cloud вместо ключа API.
  • GOOGLE_CLOUD_PROJECT – связывает запросы к модели и платежи с вашим проектом Google Cloud.
  • GOOGLE_CLOUD_LOCATION=global – таргетинг на глобальную конечную точку, где размещен gemini-3.8-flash.

🔍 Проверьте свою работу

В терминале убедитесь, что personal_assistant/agent.py импортируется без ошибок, а .env указывает на global:

cd ~/ai-agents-adk && source .venv/bin/activate
python3 -c "from personal_assistant.agent import root_agent; print(root_agent.name, root_agent.model)"
cat ~/ai-agents-adk/personal_assistant/.env

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

root_agent gemini-3.8-flash
GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=google-cloud-workshop-4210
GOOGLE_CLOUD_LOCATION=global

7. Запустите агент в терминале.

Протестируйте агент personal_assistant прямо из командной строки с помощью adk run:

cd ~/ai-agents-adk && source .venv/bin/activate
adk run personal_assistant

В окне чата [user]: отправьте сообщение, например hello. What can you do for me?, и убедитесь, что агент отвечает.

🔍 Проверьте свою работу

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

Running agent root_agent, type exit to exit.
[user]: hello. What can you do for me?
[root_agent]: Hello! I can help answer questions, explain concepts, summarize text, brainstorm ideas, and assist with writing or coding tasks. How can I help you today?
[user]: exit

Введите exit и нажмите Ввод, чтобы закрыть интерактивный сеанс CLI и вернуться к командной строке.

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

  • This API method requires billing to be enabled. Убедитесь, что GOOGLE_CLOUD_PROJECT в personal_assistant/.env соответствует вашему активному проекту, затем откройте Связанный платежный аккаунт (или скопируйте URL ниже в окно инкогнито) и свяжите активный аккаунт GDP Credit или платежный аккаунт Cloud:
https://console.cloud.google.com/billing/linkedaccount
  • API has not been used in project Включите Agent Platform API в терминале и повторите попытку через несколько секунд.
gcloud services enable aiplatform.googleapis.com

8. Запуск агента в веб-интерфейсе ADK

Ответы Markdown, полезные нагрузки событий и многоэтапные состояния гораздо проще проверять во встроенной тестовой среде браузера ADK 2. Запустите веб-интерфейс ADK из родительского каталога ~/ai-agents-adk (выше personal_assistant/):

cd ~/ai-agents-adk && source .venv/bin/activate
adk web --allow_origins "*"

Откройте веб-интерфейс ADK в браузере:

  1. Нажмите на значок Web Preview (Предварительный просмотр) на панели инструментов Cloud Shell в правом верхнем углу и выберите Change port (Изменить порт).
  2. Введите порт 8000 и нажмите Изменить и посмотреть.

Меню веб-просмотра Cloud Shell с параметрами "Предварительный просмотр на порте" и "Изменить порт"

  1. Убедитесь, что в раскрывающемся списке агентов в левом верхнем углу выбран personal_assistant, отправьте "Hello. What can you do?" и нажмите на событие ответа агента, чтобы проверить его метаданные:

Веб-интерфейс ADK 2, в котором показаны отформатированные выходные данные Markdown, а также представления Events и Traces и вкладки Info, State, Artifacts и Evals.

В веб-интерфейсе ADK 2 переключатель потоков Events (События) и Traces (Трассировки) объединен с вкладками инспектора Info (Информация), State (Состояние), Artifacts (Артефакты) и Evals (Оценки) (а также со значком графика Agent Structure (Структура агента) на верхней панели инструментов). Локальные сеансы автоматически сохраняются в personal_assistant/.adk/session.db.

🔍 Проверьте свою работу

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

INFO:     Started server process [4978]
INFO:     Waiting for application startup.
+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Завершив тестирование, нажмите Ctrl + C в терминале, чтобы остановить сервер adk web и вернуться в командную строку.

9. Очистка (необязательно)

В этой практической работе не создается постоянная платная инфраструктура, кроме вызовов Gemini с оплатой за запрос. Убедитесь, что adk web остановлен (Ctrl + C).

Удалить локальные файлы рабочей области

Чтобы удалить каталог ~/ai-agents-adk из Cloud Shell, выполните следующие действия:

cd ~
rm -rf ~/ai-agents-adk

Как удалить специальный проект (необязательно)

gcloud projects delete "$(gcloud config get-value project)" --quiet

10. Поздравляю!

Вы настроили среду Python для ADK 2 в Google Cloud, создали шаблон агента personal_assistant на основе gemini-3.8-flash в Agent Platform, изучили структуру сгенерированного пакета и протестировали его в CLI терминала и веб-интерфейсе ADK.

Чего вы достигли

  • настроили Google Cloud Shell, включили Agent Platform API и создали среду Python 3.12 с uv;
  • Создан шаблон personal_assistant с помощью adk create и изучено, как agent.py, __init__.py и .env работают вместе.
  • Протестированы многоэтапные разговоры с помощью adk run и проверены события, трассировки и сеансы с поддержкой SQLite в adk web.

Дальнейшие действия