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.
Требования
- Понимание концепций генеративного ИИ.
- Базовые навыки программирования на Python.
- Знание командной строки/терминала и интерфейса командной строки
gcloud.
Что вы узнаете
- Как настроить 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, чтобы создать платежный аккаунт без кредитной карты.
Получите бонус на рекламу
- Откройте ссылку на бонусы в окне инкогнито и войдите в аккаунт
@gmail.com. - На странице Claim Your Benefit (Получить бонус) нажмите Claim Credit (Получить бонус).

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

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

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

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

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

4. Как настроить среду
Настройте Google Cloud Shell, включите Agent Platform API и создайте изолированную виртуальную среду Python 3.12 с помощью uv.
Как настроить Cloud Shell
- Нажмите Activate Cloud Shell (Активировать Cloud Shell) (
>_) на панели инструментов консоли Google Cloud или откройте Google Cloud Shell напрямую (или скопируйте URL в окно инкогнито):
https://shell.cloud.google.com/?show=ide,terminal

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

- Выберите активный идентификатор проекта 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:

Включите необходимые 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):

Установите 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 и нажмите Ввод):
- Выберите модель для корневого агента. Введите
2, чтобы выбратьgemini-3.8-flash(вариант1выбираетgemini-3.5-flash), и нажмите Ввод. - Выберите серверную часть. Введите
2, чтобы выбрать серверную часть Google Cloud Agent Platform (вариант2в меню CLI ниже), и нажмите Ввод. - Введите идентификатор проекта Google Cloud. Нажмите Ввод, чтобы принять идентификатор проекта, указанный в скобках, или введите другой идентификатор.
- 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:

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

Просмотр: 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– импортирует классAgentADK (псевдоним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 в браузере:
- Нажмите на значок Web Preview (Предварительный просмотр) на панели инструментов Cloud Shell в правом верхнем углу и выберите Change port (Изменить порт).
- Введите порт
8000и нажмите Изменить и посмотреть.

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

В веб-интерфейсе 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.
Дальнейшие действия
- Перейти к части 2: Создание ИИ-агентов с помощью ADK: инструменты для эффективной работы
- Перейдите к части 3 Создание ИИ-агентов с помощью ADK: управление рабочими процессами агентов.
- Перейдите к части 4 Создание ИИ-агентов с помощью ADK: управление рабочими процессами графов.
- Изучите документацию по Agent Development Kit и программу обучения GEAR.