Next ‘26 开发者主旨演讲：大规模调试智能体

1. 简介

在此 Codelab 中，您将学习如何调试在 Google Cloud 上运行的 AI 代理。您将部署模拟器智能体到 Agent Runtime，使用 Cloud Observability 检测问题，并使用 Gemini Cloud Assist 和 Antigravity IDE 实时找出根本原因并修复错误。

此演示的前提是我们刚刚向模拟器代理添加了 ADK EventCompaction。这样一来，模拟器就可以使用 Gemini 定期总结其工作流程，从而减少每次向模型发送的总上下文，进而提高回答质量并降低总费用。不过，我们会发现 EventCompactionConfig 中存在 bug，导致代理出现错误！此 Codelab 将介绍如何发现此类问题并快速修复。

您将执行的操作

• 将 Marathon Simulator 代理部署到 Agent Runtime。
• 设置 Cloud Monitoring 提醒以检测代理错误。
• 使用 Cloud Trace 和 Gemini Cloud Assist 调查错误。
• 使用 Antigravity 和 MCP 找出根本原因并修补智能体。

注意：Gemini Cloud Assist 目前处于非公开预览版阶段。您无需加入许可名单即可运行此 Codelab 中的 Cloud Assist。所有 Cloud Assist 步骤都与第 8 步（可选）：使用 Cloud Assist 调查相关 - 如果您还无法访问 Cloud Assist，请跳过此页面！

所需条件

• 网络浏览器，例如 Chrome。
• Google 账号
• Antigravity（支持 Mac、Linux 和 Windows）
• Python 3.13 及更高版本。
• uv（Python 软件包管理器）

预计时长：45 分钟

预计费用：不到 5 美元

2. 准备工作

创建 Google Cloud 项目

1. 在 Google Cloud 控制台中，选择或创建 Google Cloud 项目。
2. 确保您的 Cloud 项目已启用结算功能。

设置环境

打开 Antigravity，然后登录。然后，按 cmd-shift-P（或 ctrl-shift-P）打开终端，然后输入“新建终端”。

1. 在终端中，向 Google Cloud 进行身份验证：

gcloud auth login
gcloud auth application-default login

2. 设置项目 ID：

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

启用 API

运行以下命令以启用所需的 Google Cloud API：

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 代码库并前往演示目录：

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

配置环境变量

模拟器代理使用 .env 文件进行配置。

在 Antigravity 窗口（探索器）的左侧找到 sample.env 文件：

打开 sample.env，然后使用您的实际 Google Cloud 项目 ID 更新 GCP_PROJECT_ID 字段。文件内容应如下所示：

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. 将模拟器代理部署到 Agent Runtime

现在，您将使用智能体开发套件 (ADK) 将智能体部署到 Agent Runtime。

安装依赖项

uv sync

部署到 Agent Runtime

1. 运行 adk deploy 命令。此步骤会将您的代理打包并部署到 Google Cloud (Agent Runtime)。

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...

记下生成的 Agent Runtime ID。您稍后会需要此信息！

2. 在网络浏览器中，打开 Agent Runtime 控制台。您应该会看到 simulator_agent 在 Agent Runtime 上运行，并且遥测数据收集功能处于启用状态。

5. 设置提醒政策

如需自动检测 Agent Runtime 错误，您需要在 Google Cloud 控制台中创建基于日志的提醒。

1. 前往 Cloud Monitoring - 提醒控制台。

2. 点击修改通知渠道。向下滚动到电子邮件类型，然后创建电子邮件通知渠道，以便将通知发送到您的个人电子邮件地址。点击保存。

3. 返回“提醒”信息中心，然后点击创建政策。
4. 点击屏幕右侧的创建基于日志的提醒。

5. 系统会将您重定向到 Log Explorer。粘贴以下日志查询，并将 替换为您的项目 ID。

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

此日志查询会在 Agent Runtime 代理中查找 Error 日志，其中 ReasoningEngine 是 Agent Runtime 的底层 API 名称。

6. 点击运行查询。您目前还不会看到任何日志显示，这属于正常情况。
7. 点击结果工具栏中的操作，然后点击创建日志提醒。

8. 配置基于日志的提醒。为提醒命名（任意名称），然后将严重程度设置为错误。

9. 点击下一步，进入“设置通知频率”部分（保留默认设置）。

10. 在应通知的人员部分，将提醒设置为触发您刚刚设置的电子邮件通知渠道（即My Email）。
11. 点击保存。

6. 触发突发事件

现在，代理已部署并受到监控，接下来我们尝试以会引发错误的方式调用马拉松模拟。

1. 在 Google Cloud 控制台中，前往 Agent Runtime 控制台。
2. 点击 simulator_agent。
3. 在顶部工具栏中，点击 Playground。这会启动与 ADK 代理的新会话。

4. 在会话聊天窗口中，输入 Test Simulation，然后按 Enter 键发送提示。

这会启动马拉松模拟，跟踪数千名模拟跑者沿计划路线跑步。您应该会看到对 get_runner_telemetry 和 analyze_medical_risk 的多次工具调用，因为模拟会评估比赛的多个“区域”。

几分钟后，您应该会看到代理停止运行，并返回无响应。

5. 在一分钟左右的时间内，您应该会在收件箱中看到一封电子邮件，其中会提醒您代理中出现新的突发事件。

点击查看突发事件以打开 Cloud Monitoring 控制台。继续前往下一页，在控制台中调查问题。

7. 在控制台中调查突发事件

1. 在 Cloud Monitoring 控制台中查看突发事件。您应该会看到来自模拟器代理的错误日志。

从这个视图中，很难确切地看出代理在哪个时间点失败。如需查看智能体的底层工具调用和推理流程，我们将检查智能体的轨迹。

2. 再次打开 Agent Runtime 控制台。点击 simulator_agent，然后打开轨迹标签页。

3. 点击列表中的最新轨迹。然后，点击右上角的时间轴。您应该会看到一个包含各个“span”的轨迹视图。一个 span 表示代理工作流中的模型或工具调用。

4. 点击轨迹视图中的最后一个 span。应为红色。
5. 点击 Stacktrace。您应该会看到与 Gemini API 模型调用相关的错误日志。具体而言，是 400: Invalid Argument 错误。这表示模拟器代理发送给 Gemini API 的载荷存在请求级问题。

8. [可选] 使用 Cloud Assist 调查进行调试

仅当您已加入 Gemini Cloud Assist（非公开预览版）的许可名单时，才需要执行这些步骤。否则，请前往下一页。

1. 在失败的 span 中，点击日志和事件。找到旁边带有星光按钮的“异常”日志。然后，点击调查日志。

2. 系统会从屏幕右侧的边栏启动 Cloud Assist 调查。加载大约需要 3-5 分钟。

3. 完成后，打开调查。

4. 查看调查总结。

5. 向下滚动并查看假设。Gemini Cloud Assist 应已识别出模拟器代理的 agent.py 文件中抛出 Gemini API 400 错误的特定行。

我们打开智能体的源代码，使用 Antigravity 进一步挖掘，找出问题的根本原因。前往下一页。

9. 使用 Antigravity 找出根本原因并修补问题

1. 重新打开 Antigravity。
2. 打开屏幕右上角的 Agent Manager。

3. 确保将模型设置为 Gemini 3 Flash 和规划模式。

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 的输入上下文令牌限制（约为 100 万个）。出现这种情况的原因是我们触发 EventCompaction 的频率不够高，无法有效总结模拟器代理工具调用的庞大响应。

为了解决这个问题，Antigravity 应该建议向 EventsCompactionConfig 添加 token_threshold 参数，以便在达到一定数量的令牌后，定期压缩每次调用中的上下文。

这与此 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 修复程序应用于 ADK 代理的 EventCompactionConfig，接下来可以将模拟器代理重新部署到 Agent Runtime。

1. 打开 Antigravity –> 新建终端。
2. 设置环境变量。AGENT_RUNTIME_ID 应该是 simulator_agent 的完整资源名称。您可以在 Agent Runtime 控制台的智能体列表中找到此信息。

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。点击园地
5. 输入相同的提示：Test Simulation - 然后按 Enter 键。
6. 完整的后端马拉松模拟应该需要几分钟才能运行完毕。您应该会看到多个工具调用。最终，您应该会看到如下所示的响应：

这表示模拟器已成功运行！✅

7. 打开相应 ADK 会话的 Trace 视图。
8. 您应该会看到所有“蓝色”范围，而不会看到红色错误。请注意，会话的总 token 数已超过 Gemini API 的 100 万个上下文 token 限制。没关系，因为现在 EventCompaction 在每次调用中运行的频率足够高，可以避免超出单个模型调用的总体上下文限制。

🎊 太棒了！我们已修复模拟器代理中的错误！

11. 清理

为避免系统向您的 Google Cloud 账号收取费用，请删除在此 Codelab 中创建的资源。

删除 Agent Runtime 应用

您可以通过控制台或使用 gcloud 命令（如果您有资源名称）删除推理引擎实例。为简单起见，请使用控制台：

1. 前往 Agent Runtime 页面。
2. 选择 simulator_agent –> 点击右侧的三点状按钮。
3. 点击删除。

删除 Cloud Monitoring 政策

1. 前往 Cloud Monitoring 控制台 -> 提醒。
2. 向下滚动到政策，然后点击三点状按钮以删除相应政策。

12. 🎊 恭喜！

恭喜！您刚刚成功调试了 Google Cloud 上的 AI 智能体。

您学到的内容

• 如何将代理部署到 Agent Runtime。
• 如何使用 Cloud Monitoring 提醒检测错误。
• 如何使用 Cloud Logging 和 Agent Runtime 的轨迹视图探索有效事件。
• 如何使用 Gemini Cloud Assist 调查故障。
• 如何使用 Antigravity 找出代理 bug 的根本原因并进行修补。
• 如何对 ADK 事件压缩进行微调，以处理长时间运行且工具繁重的代理回合。

后续步骤

• 详细了解 Agent Runtime。
• 详细了解智能体开发套件。
• 详细了解 Cloud Monitoring 中的提醒。
• 详细了解 Gemini Cloud Assist。