使用 Agents CLI 将 ADK 智能体部署到 Agent Runtime

1. 概览

本实验是 Kaggle 5 天 AI 智能体：Google 密集氛围编程课程的一部分。您可以在活动网站上找到其他 Codelab 和资源。

在此 Codelab 中，您将把 ADK 2.0 智能体从本地开发环境迁移到生产级部署。您将使用 agents-cli 在 Google Cloud 上的 Agent Runtime 中实时打包、验证和托管基于图的工作流。

为了探索此部署流程，您将从头开始构建 Ambient Expense Agent 的本地原型，然后再将其部署到云端。（如需深入了解如何设计此代理的核心逻辑，请参阅 Kaggle 活动网站上的基础 Codelab）。Ambient Expense Agent 可立即批准标准报销申请，同时标记较大金额的费用以供人工审核，从而简化员工费用报告流程。在后台，它使用 ADK 2.0 基于图的工作流来协调这些自动化审批和风险分析步骤。

学习内容

• 如何准备本地 Ambient Expense Agent 项目以进行云托管。
• 如何搭建必要的部署描述符和生产封装容器。
• 如何执行试运行并将代码直接部署到Agent Runtime。
• 如何使用 Cloud Trace 监控生产代理的执行轨迹。

所需条件

• 已启用结算功能的有效 Google Cloud 项目。
• 已安装 gcloud SDK 并通过身份验证。
• 已安装 uv 软件包管理器。
• 已安装 Google Antigravity IDE。

前提条件

本 Codelab 假定您熟悉以下内容：

• 使用终端导航系统。
• Python 开发基本概念。
• Google Cloud 的基本概念。

2. 设置 Google Cloud 环境

在部署之前，您必须配置 Google Cloud 项目并启用必要的 API。

👉 提示 Antigravity：

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 将在终端中显示授权网址。点击该链接，通过网络浏览器登录并授予访问权限。完成浏览器登录后，Antigravity 将恢复执行，以设置项目环境变量并启用所需的 API。

注意：如果这是一个新项目，gcloud 可能会提示您先启用 Service Usage API。如果系统要求，请点击终端中提供的链接，在 Cloud 控制台中启用该 API。

3. 设置 Agents CLI 和 ADK 技能

为了让 Antigravity 能够顺利构建和部署 ADK 智能体，它需要具备 ADK 技能组合。这些是 ADK API、项目基架、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 用户的注意事项：在此 Codelab 中，Antigravity 可能会在执行命令或编写代码之前生成实现方案或显示弹出式窗口。请务必查看并批准这些方案或弹出式窗口，以便 Antigravity 继续执行任务。

配额提示：如果在测试或开发期间配额用尽，请在 Antigravity 中将模型切换为其他可用模型。

4. 创建智能体项目

配置好云环境并安装了 CLI 技能后，您就可以为智能体生成本地代码库了。在此步骤中，您将使用 Antigravity 来搭建与 ADK 2.0 兼容的 Ambient Expense Agent 原型，该原型具有完整的功能。

针对“Kaggle AI 智能体 5 天”用户的注意事项：如果您成功完成了第 4 天的 Vibecode Ambient Expense Agent Codelab，并且希望部署现有的自定义智能体代码库，则可以跳过此基架步骤，直接前往下一步。

👉 提示 Antigravity：

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 在其 智能体开发套件 (ADK) 图形工作流中正确实现 $100 自动审批阈值和人机协同审核流程。

5. 为生产环境部署做好准备

Agent Runtime 是一项全托管式 Google Cloud 服务，可让您在生产环境中部署、管理和扩缩 AI 代理。Agent Runtime 可处理托管的运营复杂性，提供有状态的环境，并具有会话管理、长期记忆和安全的代码执行沙盒等功能。

为何要部署到 Agent Runtime？

使用 Antigravity 在本地构建代理时，您的代理会在本地机器上针对 localhost 运行。虽然本地代理非常适合快速原型设计，但会在您关闭笔记本电脑时立即停止运行。

将智能体部署到 Agent Runtime 可将工作流迁移到全托管式、始终处于运行状态的 Google Cloud 环境。这样一来，您就可以建立一个安全且实时有效的后端端点，该端点可全天候保持有效状态。在下一个 Codelab 中，您将构建一个直接连接到此云端点的 Web 前端，从而为您的代理提供一个公开网址。

此外，Agent Runtime 还提供专为 AI 智能体优化的专用基础设施，并提供内置功能，例如：

• 托管式有状态执行：内置会话管理和长期记忆持久性，可跨对话轮次。
• 安全沙盒：在隔离环境中安全地执行动态工具调用和智能体生成的代码。
• 企业级可观测性：开箱即用的遥测数据流式传输，可直接传输到 Cloud Trace 和 Cloud Logging。

如需在 Agent Runtime 上托管代理，您必须使用生产描述符、架构和端点封装容器来增强本地项目目录。

👉 提示 Antigravity：

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：Agent Runtime 用于启动资源的布局架构。

app/agent.py 中的核心代理逻辑完全不受影响，并会保留下来。

6. 打包和本地验证

在开始云端上传之前，请锁定软件包并运行本地预演，以识别潜在的依赖项冲突。

👉 提示 Antigravity：

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 以验证配置有效性并预览部署步骤，而无需预配云资源。您可以在终端中查看模拟运行输出，以确认所有文件和设置均正确无误。

7. 部署到 Agent Runtime

将 Ambient Expense Agent 部署到 Agent Runtime。

👉 提示 Antigravity：

Deploy this agent to Agent Runtime.

当 Antigravity 执行此提示时，它会激活 google-agents-cli-deploy 技能并运行 agents-cli deploy --project YOUR_PROJECT_ID --region us-west1。打包、上传和 Agent Runtime 预配过程通常需要 5-10 分钟。Antigravity 会在终端中监控部署进度，并在完成后显示您的实时端点网址。

💡 专家提示（管理超时窗口）：如果您不想在长时间部署期间锁定终端，可以指示 Antigravity 使用 --no-wait 标志异步启动部署，并稍后使用 agents-cli deploy --status 检查进度。

如果您在部署代理时遇到问题，请考虑使用其他区域。借助 Google Cloud 区域选择工具，您可以根据延迟时间、价格和碳足迹来确定最适合您项目的区域。

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 控制台 Playground 预览版手动测试代理。如需打开 Playground，请执行以下操作：

1. 在 Google Cloud 控制台中，使用导航菜单依次选择 Agent Platform > 部署。
2. 从部署列表中选择已部署的代理。
3. 点击测试场按钮以打开交互式测试对话界面。

👉 如需测试自动审批（<$100），请将以下 JSON 载荷粘贴到聊天框中：

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

您应该会收到一个 JSON 响应，其中显示了状态为“已批准”的 auto_approve 节点的输出。

👉 如需测试人工在环 (HITL) 流程，请粘贴以下 JSON 载荷。

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

这会触发 review_agent，发出警告提醒，然后暂停执行，产生一个 RequestInput（人机协同）请求，要求获得批准。

9. 监控和观察生产环境中的代理

借助 Agent Runtime，遥测会自动连接。每次互动、模型调用和工具执行都会将实时日志和 span 流式传输到您的项目中。

1. 检查轨迹：打开 Cloud Trace 控制台，以审核实时交易地图、模型延迟时间和工具执行步骤。
2. 审核日志：使用 Cloud Logging 检查实时标准输出和诊断堆栈轨迹。

3. 汇总分析：如果在基架搭建期间启用了 --bq-analytics 标志，请使用 SQL 在 BigQuery 中查询日志，以查看审批比率和对话轮次趋势。

以下 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. （可选）验证代理注册表中的注册信息

如需允许组织中的其他服务、开发者或智能体安全地发现和使用您的费用智能体，您必须在企业 Agent Registry (Gemini Enterprise) 中注册该智能体。

由于您已将代理部署到 Agent 运行时，因此该代理会自动注册到代理注册表中。在 Agent Runtime 中对智能体进行的任何未来更新或删除操作也会自动同步到 Agent Registry。

👉 提示 Antigravity 验证智能体的自动注册：

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

当 Antigravity 执行此提示时，会在终端中运行 agents-cli publish gemini-enterprise --list。此命令会查询 Agent Registry，并列出项目中的所有已注册的 Gemini Enterprise 代理，以便您确认 Ambient Expense Agent 是否处于有效状态，以及是否可在整个组织中被发现。

11. 清理

Kaggle 课程参与者：如果您正在完成本实验，并且打算继续完成下一个实验（使用 Vibecode 为 ADK 智能体部署前端），以构建前端客户端和 Pub/Sub 集成，请不要删除已部署的智能体。本实验是 Kaggle 5 天 AI 智能体课程的一部分。您需要在下一个实验中使用此有效云基础架构。

为避免 Google Cloud 账号持续产生费用，您必须在完成后关闭并清理已部署的资源。

👉 提示 Antigravity：

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 以获取远程代理运行时 ID，然后以编程方式从 Vertex AI 中删除实时引擎实例。
2. 清理本地工作区：从项目根目录中移除过时的 deployment_metadata.json 文件。
3. 清理 Artifact Registry：执行 gcloud artifacts docker images delete 以从 Artifact Registry 中移除构建的容器映像，从而释放云存储空间。

12. 恭喜

恭喜！您已在 Google Cloud 上成功部署并验证了生产级 Ambient Expense Agent。

要点回顾

• Google Cloud 设置：已配置项目凭据并已启用所需的平台 API。
• 工具和技能：已安装 agents-cli 并将 ADK 辅助技能加载到 Antigravity 中。
• 生产环境基架：为 ADK 2.0 智能体生成的 Agent Runtime 基架。
• 本地验证：创建了确定性锁定文件 (uv lock) 并执行了试运行检查。
• 云部署：在受管理的 Agent Runtime 基础设施上实时托管智能体。
• 可观测性和分析：在 Cloud Trace 中跟踪执行情况，并在 BigQuery 中分析遥测数据。
• 企业发现：在企业代理注册表中经过验证的自动注册。

后续步骤

• 执行 BigQuery 分析：在 BigQuery 中查询代理的遥测日志，以分析一段时间内的审批比率和对话轮次趋势。
• Vibe to Live Codelab：使用 Google Antigravity 在 Cloud Run 上开发前端客户端，并将其直接连接到您的实时 Agent Runtime 后端端点。

赢得 Kaggle 5 天 AI 智能体徽章 🎉

您是否已完成本实验，并参加了 Kaggle 的“5 天 AI 智能体：Google 氛围编程强化课程”？领取您的完成徽章：

获得“AI 智能体 5 日”徽章

参考

• 智能体开发套件 (ADK) 文档
• Gemini Enterprise Agent Platform 运行时
• Agents CLI (agents-cli) 参考指南
• Gemini Enterprise Agent 注册表概览
• Google Cloud Trace 文档