Следующая основная презентация для разработчиков ‘26: Отладка агентов в масштабе предприятия

1. Введение

В этом практическом занятии вы научитесь отлаживать агентов ИИ, работающих в Google Cloud. Вы развернете агент-симулятор в Agent Runtime, используете Cloud Observability для обнаружения проблем, а также Gemini Cloud Assist и Antigravity IDE для выявления и устранения ошибок в режиме реального времени.

Суть этой демонстрации заключается в том, что мы только что добавили ADK EventCompaction в агент симулятора. Это позволяет симулятору периодически суммировать свой рабочий процесс с помощью Gemini, уменьшая общий контекст, отправляемый модели на каждом этапе, — тем самым улучшая качество ответа и снижая общие затраты. Но мы узнаем, что в нашем EventCompactionConfig есть ошибка, вызывающая сбои в работе агента! В этом практическом занятии мы рассмотрим, как обнаружить подобную проблему и быстро ее исправить.

Что вы будете делать

• Разверните агент симулятора марафона в среде выполнения агентов .
• Настройте оповещения облачного мониторинга для обнаружения ошибок агента.
• Для выявления и устранения ошибок используйте Cloud Trace и Gemini Cloud Assist .
• Выявите первопричину и устраните уязвимость с помощью Antigravity и MCP.

Примечание: Gemini Cloud Assist в настоящее время находится в режиме закрытого предварительного просмотра. Для выполнения этого практического задания вам не обязательно быть в списке разрешенных пользователей Cloud Assist. Все шаги Cloud Assist относятся к пункту #8 (необязательно): Используйте Cloud Assist Investigations — пропустите эту страницу, если у вас пока нет доступа к Cloud Assist!

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

• Веб-браузер, например Chrome .
• Аккаунт Google
• Antigravity (поддерживает Mac, Linux и Windows)
• Python 3.13+ .
• uv (менеджер пакетов Python)

Примерное время: 45 минут

Ориентировочная стоимость: менее 5 долларов США.

2. Прежде чем начать

Создайте проект в Google Cloud.

1. В консоли Google Cloud выберите или создайте проект Google Cloud .
2. Убедитесь, что для вашего облачного проекта включена функция выставления счетов.

Настройте свою среду

Откройте Antigravity и войдите в систему. Затем откройте терминал , нажав cmd-shift-P (или ctrl-shift-P ), и введите "Создать новый терминал".

1. Пройдите аутентификацию в Google Cloud через терминал:

gcloud auth login
gcloud auth application-default login

2. Укажите идентификатор вашего проекта:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

Включить API

Выполните следующую команду, чтобы включить необходимые API Google Cloud:

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

Если вы включены в список разрешенных пользователей Gemini Cloud Assist (закрытая предварительная версия), активируйте следующие дополнительные API:

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. Настройка агента симулятора

На этом шаге вы клонируете репозиторий демонстрационных файлов и настроите переменные среды для агента симулятора.

Клонируйте репозиторий

Клонируйте репозиторий next-26-keynotes и перейдите в каталог demo:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

Настройка переменных среды

Агент симулятора использует файл .env для настройки.

Найдите файл sample.env в левой части окна Antigravity (в проводнике Windows):

Откройте sample.env и обновите поле GCP_PROJECT_ID , указав фактический идентификатор вашего проекта Google Cloud. Файл должен выглядеть примерно так:

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

Мы обеспечиваем интеграцию с OpenTelemetry для сбора подробных данных о вызовах инструментов агента и ходе его работы.

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

Теперь вы развернете агента в среде выполнения агентов , используя комплект разработки агентов (ADK).

Установите зависимости

uv sync

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

1. Выполните команду adk deploy . На этом шаге ваш агент будет упакован и развернут в Google Cloud (среда выполнения агентов).

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

Выполнение этой процедуры может занять до 5 минут. В итоге вы должны увидеть примерно такой результат:

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

Запишите сгенерированный идентификатор среды выполнения агента. Он понадобится вам позже!

2. Откройте консоль Agent Runtime в веб-браузере. Вы должны увидеть запущенный в Agent Runtime simulator_agent с включенным сбором телеметрии.

5. Настройте политику оповещений.

Для автоматического обнаружения ошибок Agent Runtime необходимо создать оповещение на основе журналов в консоли Google Cloud.

1. Перейдите в консоль «Мониторинг облака — оповещения» .

2. Нажмите «Редактировать каналы уведомлений». Прокрутите вниз до раздела «Тип электронной почты» , затем создайте канал уведомлений по электронной почте для отправки на ваш личный адрес. Нажмите «Сохранить» .

3. Вернитесь на панель управления оповещениями и нажмите «Создать политику» .
4. В правой части экрана нажмите «Создать оповещение на основе журнала» .

5. Вы будете перенаправлены в Log Explorer . Вставьте следующий запрос логов, заменив на идентификатор вашего проекта.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

Этот запрос к журналам ищет журналы ошибок в вашем агенте Agent Runtime, где ReasoningEngine — это базовое имя API для Agent Runtime.

6. Нажмите «Выполнить запрос» . Пока никаких записей в журнале не отобразится — это нормально.
7. На панели результатов нажмите «Действия» , затем нажмите «Создать оповещение в журнале» .

8. Настройте оповещение на основе логов. Присвойте оповещению имя (любое), затем установите уровень серьезности на «Ошибка» .

9. Нажмите «Далее» в разделе «Установка частоты уведомлений» (оставьте значения по умолчанию).

10. В поле «Кто должен получать уведомления?» настройте оповещение так, чтобы оно запускало только что настроенный вами канал уведомлений по электронной почте (например, My Email »).
11. Нажмите « Сохранить».

6. Инициировать инцидент

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

1. В консоли Google Cloud перейдите в консоль Agent Runtime .
2. Нажмите simulator_agent .
3. На верхней панели инструментов нажмите «Игровая площадка». Это запустит новую сессию с агентом ADK.

4. В окне чата сессии введите Test Simulation и нажмите Enter , чтобы отправить запрос.

Это запустит симуляцию марафона, отслеживая тысячи смоделированных бегунов по запланированному маршруту. Вы должны увидеть несколько вызовов инструментов get_runner_telemetry и analyze_medical_risk , поскольку симуляция оценивает несколько «зон» гонки.

Через несколько минут вы должны увидеть, что агент остановится и не будет возвращать никакого ответа.

5. Примерно через минуту в ваш почтовый ящик должно прийти письмо с уведомлением о новом инциденте в системе агента.

Нажмите «Просмотреть инцидент» , чтобы открыть консоль мониторинга облака. Перейдите на следующую страницу, чтобы изучить проблему в консоли.

7. Проведите расследование инцидента в консоли.

1. Просмотрите инцидент в консоли облачного мониторинга. Вы должны увидеть журналы ошибок, поступающие от агента симулятора.

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

2. Снова откройте консоль Agent Runtime. Щелкните simulator_agent , затем откройте вкладку Traces .

3. Щелкните по самой последней трассировке в списке. Затем в правом верхнем углу щелкните «Временная шкала ». Вы увидите представление трассировки с отдельными «отрезками». Один отрезок представляет собой вызов модели или инструмента в рамках рабочего процесса агента.

4. Щелкните по последнему фрагменту в окне трассировки. Он должен быть красным .
5. Нажмите «Трассировка стека» . Вы должны увидеть журналы ошибок, относящиеся к вызову модели API Gemini. В частности, ошибка 400: Invalid Argument . Это указывает на проблему на уровне запроса с полезной нагрузкой, которую агент симулятора отправил в API Gemini.

8. [Необязательно] Используйте Cloud Assist Investigations для отладки.

Выполняйте эти шаги только в том случае, если вы включены в список разрешенных пользователей Gemini Cloud Assist (закрытая предварительная версия). В противном случае перейдите на следующую страницу.

1. В течение периода сбоя нажмите «Журналы и события» . Найдите журнал «Исключение» со значком мерцающей кнопки рядом с ним. Затем нажмите «Исследовать журнал» .

2. Это запустит проверку Cloud Assist из боковой панели в правой части экрана. Загрузка займет около 3-5 минут.

3. После завершения расследования начните его.

4. Ознакомьтесь с кратким обзором расследования .

5. Прокрутите вниз и просмотрите гипотезы . Gemini Cloud Assist должен был определить конкретную строку в файле agent.py агента симулятора, которая вызывает ошибку Gemini API 400.

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

9. Используйте антигравитацию, чтобы выявить первопричину и устранить проблему.

1. Возобновите работу антигравитации.
2. Откройте менеджер агентов в правом верхнем углу экрана.

3. Убедитесь, что модель настроена на режим Gemini 3 Flash и Planning .

4. Введите следующую подсказку и нажмите Enter .

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.    

Вы должны увидеть, как Antigravity анализирует код в agent.py и ищет соответствующие проблемы на GitHub:

Основная причина ошибки Gemini API 400 заключается в превышении лимита токенов контекста ввода Gemini 3 Flash, составляющего примерно 1 миллион. Это происходит потому, что мы недостаточно часто запускаем EventCompaction, чтобы эффективно обобщить огромный объем ответов от инструментов Simulator Agents .

Для решения этой проблемы Antigravity следует предложить добавить параметр token_threshold в EventsCompactionConfig , чтобы периодически сжимать контекст при каждом вызове, как только будет достигнуто определенное количество токенов.

Это соответствует решению, предложенному в этом обсуждении на GitHub .

Примените исправление к agent.py.

Убедитесь, что вы видите что-то похожее на это:

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

Важно отметить, что token_threshold и event_retention_size должны быть установлены!

10. Повторно разверните и проверьте исправление.

Теперь, когда мы применили исправление token_threshold к EventCompactionConfig агента ADK, мы можем повторно развернуть агент симулятора в среде выполнения агентов.

1. Откройте «Антигравитация» –> Новый терминал .
2. Установите переменные среды. Параметр AGENT_RUNTIME_ID должен быть полным именем ресурса вашего simulator_agent . Его можно найти в консоли среды выполнения агента — список агентов.

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

3. Повторно разверните агента:

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

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

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

4. Откройте консоль Agent Runtime. Снова откройте simulator_agent . Нажмите Playground.
5. Введите ту же команду: Test Simulation , затем нажмите Enter .
6. Полная симуляция работы бэкэнда Marathon должна занять несколько минут. Вы должны увидеть несколько вызовов инструментов. В итоге вы должны увидеть ответ примерно такого вида:

Это означает, что симулятор успешно запущен! ✅

7. Откройте окно трассировки для этой сессии ADK.
8. Вы должны увидеть все "синие" сегменты без красных ошибок. Обратите внимание, что общее количество токенов в сессиях превышает лимит контекстных токенов в 1 миллион, установленный API Gemini. Это нормально, потому что теперь EventCompaction выполняется достаточно часто в рамках каждого вызова, чтобы избежать превышения общего лимита контекстных токенов для отдельных вызовов моделей.

🎊 Ура! Мы исправили ошибку в агенте симулятора!

11. Уборка

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

Удалите приложение Agent Runtime.

Удалить экземпляр Reasoning Engine можно через консоль или с помощью команды gcloud (если известно имя ресурса). Для простоты используйте консоль:

1. Перейдите на страницу "Среда выполнения агента" .
2. Выберите simulator_agent –> нажмите кнопку с тремя точками справа.
3. Нажмите «Удалить» .

Удалите политику мониторинга облака.

1. Перейдите в консоль облачного мониторинга -> Оповещения .
2. Прокрутите страницу вниз до раздела «Политики» , затем нажмите кнопку с тремя точками, чтобы удалить политику.

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

Поздравляем! Вы успешно отладили ИИ-агента в Google Cloud.

Что вы узнали

• Как развернуть агентов в Agent Runtime .
• Как обнаруживать ошибки с помощью оповещений облачного мониторинга .
• Как просматривать активные инциденты с помощью Cloud Logging и трассировочного представления Agent Runtime .
• Как исследовать сбои с помощью Gemini Cloud Assist .
• Как использовать Antigravity для выявления и устранения ошибок в агентах.
• Как точно настроить ADK Event Compaction для обработки длительных и ресурсоемких циклов работы агентов.

Следующие шаги

• Узнайте больше об Agent Runtime .
• Узнайте больше о комплекте разработки агентов .
• Узнайте больше об оповещениях в облачном мониторинге .
• Узнайте больше о Gemini Cloud Assist .