Разверните агент ADK в Agent Runtime с помощью Agent CLI.

1. Обзор

Эта лабораторная работа является частью 5-дневного интенсивного курса программирования Vibe Coding Course от Google на платформе Kaggle. Дополнительные лабораторные работы и ресурсы можно найти на сайте мероприятия .

В этом практическом занятии вы переведете агент ADK 2.0 из локальной среды разработки в рабочую среду. Вы будете использовать agents-cli для упаковки, проверки и размещения вашего рабочего процесса на основе графов в режиме реального времени на Agent Runtime в Google Cloud.

Чтобы изучить этот процесс развертывания, вы создадите локальный прототип Ambient Expense Agent с нуля, прежде чем развернуть его в облаке. (Более подробное описание проектирования основной логики этого агента см. в базовых практических заданиях на сайте мероприятия Kaggle ). Ambient Expense Agent упрощает отчетность о расходах сотрудников, мгновенно утверждая стандартные заявки и отмечая более крупные расходы для проверки человеком. В основе его работы лежит графический рабочий процесс ADK 2.0, который координирует эти автоматизированные утверждения и этапы анализа рисков.

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

• Как подготовить локальный проект Ambient Expense Agent для размещения в облаке.
• Как создать необходимые дескрипторы развертывания и оболочки для производственной среды.
• Как проводить пробные запуски и развертывать код непосредственно в Agent Runtime .
• Как отслеживать трассировку выполнения вашего производственного агента с помощью Cloud Trace.

Что вам понадобится

• Активный проект в Google Cloud с включенной функцией выставления счетов.
• Установлен и авторизован SDK gcloud .
• Установлен менеджер пакетов UV .
• Установлена ​​среда разработки Google Antigravity IDE .

Предварительные требования

В этом практическом занятии предполагается, что вы хорошо знакомы со следующими темами:

• Навигация по системе осуществляется с помощью терминала.
• Основные концепции разработки на Python.
• Основные концепции Google Cloud.

2. Настройте свою среду Google Cloud.

Перед развертыванием необходимо настроить проект Google Cloud и включить необходимые API.

👉 Мгновенная антигравитация:

Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).

Когда Antigravity выполнит это приглашение, он предложит и запустит необходимые команды терминала gcloud для настройки вашего проекта и включения сервисов. На этапе аутентификации Antigravity отобразит URL-адрес авторизации в терминале. Щелкните ссылку, чтобы войти через веб-браузер и предоставить доступ. После завершения входа в браузер Antigravity возобновит выполнение, чтобы установить переменные среды вашего проекта и включить необходимые API.

Примечание: Если это новый проект, gcloud может сначала предложить вам включить API использования сервиса. Перейдите по ссылке, указанной в терминале, чтобы включить его в консоли Cloud, если это потребуется.

3. Настройка навыков CLI и ADK для агентов.

Для эффективной сборки и развертывания агентов ADK в Antigravity необходим набор инструментов ADK . Это пакеты, включающие ссылки на API ADK, структуру проекта, рабочий процесс развертывания agents-cli и оценку. Установка набора инструментов agents-cli также интегрирует эти инструменты в ваш агент разработки, позволяя ему управлять полным жизненным циклом агента — от локальной структуры до развертывания в облаке.

👉 Скопируйте и вставьте следующую подсказку в Antigravity:

Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.

Когда Antigravity отправляет это приглашение, он запускает в терминале uvx google-agents-cli setup для установки CLI и сопутствующих навыков. Затем он запускает agents-cli info для проверки установки и отображает список недавно установленных навыков домена (таких как google-agents-cli-deploy и google-agents-cli-workflow ) непосредственно в чате.

Примечание для пользователей Antigravity: Во время выполнения этого практического задания Antigravity может генерировать планы реализации или отображать всплывающие окна перед выполнением команд или написанием кода. Обязательно просмотрите и подтвердите эти планы или всплывающие окна, чтобы Antigravity мог продолжить выполнение задач.

Совет по использованию квоты: Если во время тестирования или разработки у вас закончится квота, переключитесь в Antigravity на другую доступную модель.

4. Создайте свой проект агента.

После настройки облачной среды и установки навыков работы с командной строкой вы готовы сгенерировать локальный код для вашего агента. На этом этапе вы используете Antigravity для создания полнофункционального прототипа агента Ambient Expense Agent, совместимого с ADK 2.0.

Примечание для пользователей Kaggle 5 дней AI Agents : Если вы успешно завершили этот практический семинар Vibecode по созданию агента для расчета расходов на окружающую среду (Ambient Expense Agent Codelab) за 4-й день и предпочитаете развернуть существующий код собственного агента, вы можете пропустить этот этап создания шаблона и перейти к следующему шагу.

👉 Мгновенная антигравитация:

Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.

Когда Antigravity выполнит эту команду, он использует недавно установленные функции генерации кода для запуска agents-cli scaffold create expense-agent --adk в терминале. Затем он проверит и скорректирует сгенерированный прототип кода, чтобы убедиться, что ваш expense-agent правильно реализует порог автоматического утверждения $100 и процесс проверки с участием человека в рамках рабочего процесса графа Agent Development Kit (ADK) .

5. Подготовка к внедрению в производство.

Agent Runtime — это полностью управляемый сервис Google Cloud, позволяющий развертывать, управлять и масштабировать агентов ИИ в производственной среде. Agent Runtime берет на себя операционные сложности хостинга, предлагая среду с сохранением состояния, включающую такие функции, как управление сессиями, долговременную память и безопасные песочницы для выполнения кода.

Почему развертывание в среде выполнения агента?

При локальной сборке агентов с помощью Antigravity ваш агент запускается на локальном компьютере по localhost . Хотя это отлично подходит для быстрого прототипирования, локальные агенты перестают работать в тот момент, когда вы закрываете ноутбук.

Развертывание вашего агента в Agent Runtime переносит ваш рабочий процесс в полностью управляемую, постоянно работающую среду Google Cloud. Это создает безопасную, работающую круглосуточно конечную точку бэкэнда. В следующем практическом занятии вы создадите веб-интерфейс, который будет напрямую подключаться к этой облачной конечной точке, предоставляя вашему агенту публичный URL-адрес.

Кроме того, Agent Runtime предоставляет выделенную инфраструктуру, оптимизированную специально для агентов искусственного интеллекта, и предлагает встроенные возможности, такие как:

• Управляемое выполнение с сохранением состояния: встроенное управление сессиями и сохранение данных в долговременной памяти между этапами диалога.
• Безопасная песочница: обеспечивает безопасное выполнение динамических вызовов инструментов и сгенерированного агентом кода в изолированных средах.
• Наблюдаемость в корпоративной среде: готовая к использованию потоковая передача телеметрии непосредственно в Cloud Trace и Cloud Logging.

Для размещения агента в среде выполнения Agent Runtime необходимо дополнить локальный каталог проекта производственными дескрипторами, схемами и оболочками конечных точек.

👉 Мгновенная антигравитация:

Scaffold the production deployment files for Agent Runtime.

Когда Antigravity выполнит эту команду, она запустит agents-cli scaffold enhance --deployment-target agent_runtime --yes в корневом каталоге вашего проекта. Эта команда просканирует ваш каталог и автоматически сгенерирует:

• app/agent_runtime_app.py : Оболочка сервиса, готовая к использованию в производственной среде.
• deployment_metadata.json : Схема структуры, используемая средой выполнения агента для запуска ресурсов.

Основная логика работы вашего агента в app/agent.py остаётся полностью неизменной и сохраненной.

6. Упаковка и локальная проверка

Перед началом загрузки в облако заблокируйте свои пакеты и проведите локальный пробный запуск, чтобы выявить потенциальные конфликты зависимостей.

👉 Мгновенная антигравитация:

Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.

Когда Antigravity выполнит эту команду, сначала в терминале запустится uv lock для создания детерминированного файла блокировки, обеспечивающего согласованность версий библиотек в облаке. Затем будет выполнена agents-cli deploy --dry-run для проверки корректности конфигурации и предварительного просмотра шагов развертывания без выделения облачных ресурсов. Вы можете просмотреть вывод команды `dry-run` в терминале, чтобы убедиться в правильности всех файлов и настроек.

7. Развертывание в среде выполнения агента.

Разверните свой агент Ambient Expense в среде выполнения агентов.

👉 Мгновенная антигравитация:

Deploy this agent to Agent Runtime.

Когда Antigravity выполнит эту команду, он активирует навык google-agents-cli-deploy и запустит agents-cli deploy --project YOUR_PROJECT_ID --region us-west1 . Процесс упаковки, загрузки и подготовки среды выполнения агента обычно занимает 5–10 минут . Antigravity будет отслеживать ход развертывания в терминале, и после завершения отобразит URL-адрес вашей рабочей конечной точки.

💡 Полезный совет (управление временными окнами): Если вы предпочитаете не блокировать терминал во время длительных развертываний, вы можете указать Antigravity использовать флаг --no-wait для асинхронного запуска развертывания и проверить ход выполнения позже с помощью agents-cli deploy --status .

Если у вас возникли проблемы с развертыванием агента, рассмотрите возможность использования другого региона. Инструмент Google Cloud Region Picker поможет вам определить оптимальный регион для вашего проекта, исходя из задержки, цены и углеродного следа.

8. Проверьте своего агента.

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

👉 Запросите у Antigravity подтверждение работы развернутого движка:

Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.

Примечание: Если Antigravity запустит этот тестовый запрос на вашей рабочей точке, и обнаружит какие-либо ошибки развертывания или выполнения, он автоматически попытается отладить проблему, применить необходимые исправления кода и повторно развернуть агент.

В качестве альтернативы вы можете протестировать своего агента вручную, используя предварительную версию Cloud Console Playground . Чтобы открыть Playground:

1. В консоли Google Cloud используйте меню навигации, чтобы выбрать Agent Platform > Deployments .
2. Выберите развернутый агент из списка развертываний.
3. Нажмите кнопку «Игровая площадка» , чтобы открыть интерактивный интерфейс тестового чата.

👉 Чтобы протестировать автоматическое одобрение (при заказе на сумму менее 100 долларов) , вставьте следующий JSON-код в окно чата:

{"data": {"amount": 50.0, "submitter": "[e-mail]", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}

Вы должны получить JSON-ответ, содержащий вывод узла auto_approve со статусом "approved".

👉 Чтобы протестировать сценарий "человек в цикле" (Human-in-the-Loop, HITL) , вставьте следующий JSON-код.

{"data": {"amount": 150.0, "submitter": "[e-mail]", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}

Это запустит review_agent, выдаст предупреждение, а затем приостановит выполнение, выдав RequestInput (с участием человека), запрашивающий подтверждение.

9. Следите за своим производственным агентом и контролируйте его работу.

С Agent Runtime телеметрия автоматически подключается. Каждое взаимодействие, вызов модели и выполнение инструмента передают в режиме реального времени журналы и данные в ваш проект.

1. Проверка трассировки : Откройте консоль Cloud Trace , чтобы проверить карты транзакций в реальном времени, задержки модели и этапы выполнения инструментов.
2. Журналы аудита : Используйте Cloud Logging для анализа стандартного вывода в реальном времени и диагностических трассировок стека.

3. Сводная аналитика : Если флаг --bq-analytics был включен во время создания шаблона, выполните запрос к журналам в BigQuery с помощью SQL, чтобы просмотреть коэффициенты одобрения и тенденции оборота разговоров.

Приведенный ниже SQL-запрос является примером расчета коэффициентов одобрения. Вы можете настроить этот запрос в Antigravity под свой конкретный проект и набор данных BigQuery:

SELECT
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
  COUNT(1) AS total_processed,
  SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
  `[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
  agent = 'expense_processor';

10. (Необязательно) Подтвердите регистрацию в реестре агентов.

Для того чтобы другие сервисы, разработчики или агенты в вашей организации могли безопасно обнаруживать и использовать ваш агент расходов, он должен быть зарегистрирован в корпоративном реестре агентов (Gemini Enterprise).

Поскольку вы развернули свой агент в Agent Runtime, он автоматически регистрируется в реестре агентов. Любые будущие обновления или удаления вашего агента в Agent Runtime также будут автоматически синхронизироваться с реестром агентов.

👉 Запросите у Antigravity подтверждение автоматической регистрации вашего агента:

Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.

Когда Antigravity выполнит эту команду, в терминале запустится agents-cli publish gemini-enterprise --list . Это запросит реестр агентов и отобразит список всех зарегистрированных агентов Gemini Enterprise в вашем проекте, что позволит вам убедиться в том, что ваш агент Ambient Expense активен и доступен для обнаружения во всей вашей организации.

11. Уборка

Участники курса Kaggle : Если вы выполняете эту лабораторную работу в рамках 5-дневного курса Kaggle по ИИ-агентам и планируете продолжить работу над следующей лабораторной работой ( Vibecode и развертывание интерфейса для агента ADK ) для создания клиентского интерфейса и интеграции Pub/Sub, не удаляйте развернутый агент . Вам понадобится эта активная облачная инфраструктура для следующей лабораторной работы.

Чтобы избежать постоянных расходов в вашем аккаунте Google Cloud, необходимо отключать и очищать развернутые ресурсы после завершения работы.

👉 Мгновенная антигравитация:

Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.

Когда Antigravity выполнит эту команду, она автоматизирует весь процесс очистки ресурсов:

1. Удаление развернутого агента : программа считывает файл deployment_metadata.json для получения идентификатора среды выполнения удаленного агента, а затем программно удаляет работающий экземпляр движка из Vertex AI.
2. Очистка локального рабочего пространства : эта команда удаляет устаревший файл deployment_metadata.json из корневой папки вашего проекта.
3. Очистка реестра артефактов : выполняется команда gcloud artifacts docker images delete для удаления собранных образов контейнеров из реестра артефактов, освобождая место в облачном хранилище.

12. Поздравляем!

Поздравляем! Вы успешно развернули и проверили работоспособность агента Ambient Expense в производственной среде Google Cloud.

Что вы узнали

• Настройка Google Cloud : настроены учетные данные проекта и включены необходимые API платформы.
• Инструментарий и навыки : Установлен agents-cli и загружены сопутствующие навыки ADK в Antigravity.
• Производственная среда разработки : Сгенерированная среда выполнения агента ADK 2.0.
• Локальная проверка : Созданы детерминированные файлы блокировки ( uv lock ) и выполнены пробные проверки.
• Развертывание в облаке : Разместите свой агент в режиме реального времени на управляемой инфраструктуре среды выполнения агентов.
• Наблюдаемость и аналитика : отслеживание выполнения в Cloud Trace и анализ телеметрии в BigQuery.
• Enterprise Discovery : Подтверждена автоматическая регистрация в корпоративном реестре агентов.

Что дальше?

• Используйте аналитику BigQuery : запрашивайте журналы телеметрии ваших агентов в BigQuery, чтобы анализировать коэффициенты одобрения и тенденции оборота разговоров с течением времени.
• Vibe to Live Codelab : Используйте Google Antigravity для разработки клиентского интерфейса на Cloud Run и подключите его напрямую к рабочей точке бэкэнда Agent Runtime.

Получите значок Kaggle "5-дневный курс по работе с ИИ-агентами" 🎉

Выполнили эту лабораторную работу в рамках 5-дневного интенсивного курса программирования Vibe Coding Course от Google на Kaggle? Получите значок за завершение курса:

Получите 5-дневный значок "Агенты ИИ"

Ссылки

• Документация по комплекту разработки агентов (ADK)
• Среды выполнения платформы агентов Gemini Enterprise
• Руководство по использованию интерфейса командной строки агентов ( agents-cli )
• Обзор реестра корпоративных агентов Gemini
• Документация Google Cloud Trace