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

1. 简介

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

此演示的前提是，我们刚刚向模拟器智能体添加了 ADK EventCompaction。这样，模拟器就可以使用 Gemini 定期汇总其工作流，从而减少每次轮换时发送给模型的总上下文，进而提高响应质量并降低总费用。但是，我们将了解到 EventCompactionConfig 中存在 bug，导致智能体出现错误！此 Codelab 将逐步介绍如何找到此类问题并快速修复。

您将执行的操作

• 将 Marathon 模拟器智能体部署到 Agent Runtime 。
• 设置 Cloud Monitoring 提醒 以检测智能体错误。
• 使用 Cloud Trace 和 Gemini Cloud Assist 调查错误。
• 使用 Antigravity 和 MCP 找出智能体根源并修补智能体。

注意：Gemini Cloud Assist 目前为非公开预览版。您无需加入 Cloud Assist 许可名单即可运行此 Codelab。所有 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），然后输入“Create New Terminal”，打开终端 。

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. 点击修改通知渠道 。向下滚动到 Email 类型，然后创建一个电子邮件通知渠道以发送到您的个人电子邮件地址。点击保存 。

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 智能体中查找错误 日志，其中 ReasoningEngine 是 Agent Runtime 的底层 API 名称。

6. 点击运行查询 。您暂时不会看到任何日志显示 - 这是预期行为。
7. 在结果工具栏中，点击操作 ，然后点击创建日志提醒 。

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

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

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

6. 触发突发事件

现在智能体已部署并受到监控，接下来我们尝试以抛出错误的方式调用 Marathon 模拟。

1. 在 Google Cloud 控制台中，前往 Agent Runtime 控制台。
2. 点击 simulator_agent 。
3. 在顶部工具栏中，点击 Playground 。这将使用 ADK 智能体启动新会话。

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

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

几分钟后，您应该会看到智能体停止运行，并且没有响应。

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

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

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

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

在此视图中，很难确切地看到智能体在哪个时间点失败。如需查看智能体的底层工具调用和推理流程，我们将检查智能体的跟踪记录。

2. 再次打开 Agent Runtime 控制台。点击 simulator_agent ，然后打开 跟踪记录 标签页。

3. 点击列表中的最新跟踪记录。然后，点击右上角的时间轴 。您应该会看到包含各个“跨度”的跟踪记录视图。一个跨度表示智能体工作流中的模型或工具调用。

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

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

仅当您已加入 Gemini Cloud Assist（非公开预览版）许可名单时，才需要按照以下步骤操作。否则，请继续前往下一页。

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

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 参数，以便在达到一定数量的 token 后，定期压缩每次调用中的 上下文。

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

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

7. 打开该 ADK 会话的跟踪记录视图。
8. 您应该会看到所有“蓝色”跨度，没有红色错误。请注意，会话的总令牌数如何超出 Gemini API 的 100 万个上下文令牌限制。没关系，因为现在 EventCompaction 在每次调用中运行的频率足够高，可以避免超出单个模型调用的整体上下文限制。

🎊 太棒了！我们修补了模拟器智能体中的错误！

11. 清理

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

删除 Agent Runtime 应用

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

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

删除 Cloud Monitoring 政策

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

12. 🎊 恭喜！

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

您学到的内容

• 如何将智能体部署到 Agent Runtime 。
• 如何使用 Cloud Monitoring 提醒检测错误。
• 如何使用 Cloud Logging 和 Agent Runtime 的跟踪记录视图 探索活跃的突发事件。
• 如何使用 Gemini Cloud Assist 调查失败。
• 如何使用 Antigravity 找出智能体 bug 的根源并修补 bug。
• 如何微调 ADK Event Compaction 以处理长时间运行、工具繁重的智能体轮换。

后续步骤

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