部署鸿沟：本地运行正常，生产环境却崩溃
你花了数周时间构建了一个 AI 智能体。它在你的笔记本电脑上运行完美。评估分数看起来不错。你的团队准备向用户展示它。然后你尝试部署它，一切都崩溃了。
这是使用 Google Agent Development Kit (ADK) 构建智能体的团队经常遇到的场景。本地开发环境是宽容的。你控制着 Python 版本，环境变量在你的 shell 中设置，没有网络策略阻止出站调用。但生产环境不同。你需要容器镜像、具有正确 IAM 角色的服务账户、密钥管理、能够扩展的部署目标，以及在出现问题时回滚的方法。
痛苦不仅仅是技术层面的，也是组织层面的。开发者可能推送了一个在他们机器上正常但在 CI 中失败的 Dockerfile，因为基础镜像不对。队友可能在源代码中硬编码了 API 密钥，而不是使用 Secret Manager。其他人可能部署到了错误的区域。这些错误中的每一个都是可以避免的，但它们之所以发生，是因为部署过程是手动的、没有文档记录的，并且是脆弱的。
为什么这个问题会随着时间恶化
当你只有一个智能体和一个开发者时，临时部署还可以应付。你 SSH 到服务器，拉取最新代码，然后重启服务。但这无法扩展。
随着团队的成长，你需要：
- 可复现的构建。 相同的代码每次应该产生相同的容器镜像。
- 密钥隔离。 API 密钥和服务账户凭据绝不能存在于源代码控制中。
- 环境一致性。 开发、预发布和生产环境应该尽可能相似。
- 回滚能力。 如果部署引入了回归，你需要在几秒内回滚，而不是几小时。
- 审计追踪。 你需要知道谁在什么时候部署了什么到哪个环境。
没有这些，每次部署都是一场赌博。代价不仅仅是停机时间。还有用户失去的信任，以及浪费在调试基础设施而不是改进智能体上的工程时间。
一个好的解决方案应该改变什么
一个用于 AI 智能体的部署工具应该做三件事：
- 抽象掉基础设施样板代码。 你不应该每次部署时都要从头编写 Terraform 模块或调试 Docker 网络问题。
- 默认强制执行最佳实践。 密钥应该从密钥管理器注入。服务账户应该遵循最小权限原则。容器镜像应该使用可复现的工具构建。
- 通过一致的界面支持多个部署目标。 无论你选择 Cloud Run 以获得简单性，GKE 以获得完全的 Kubernetes 控制，还是 Agent Runtime 以获得托管的智能体基础设施，部署命令应该感觉相同。
这就是一个专门为 ADK 智能体部署设计的 CLI 工具能够帮助的地方。一个值得检查的选项是 google-agents-cli-deploy 技能，它是更广泛的 Google Agents CLI 生态系统的一部分。
介绍 google-agents-cli-deploy
google-agents-cli-deploy 技能为使用 Google Agent Development Kit 构建的智能体提供部署工作流。它将 Terraform、Docker 和云部署逻辑封装到一个经过测试的管道中，通过 agents-cli 命令行工具暴露出来。
这不是一个通用的部署工具。它专门为 ADK 智能体设计，并理解它们的结构：AdkApp 模式、会话管理、智能体身份以及 ADK 项目携带的部署元数据。如果你的项目是用 ADK 脚手架生成的，这个工具知道如何打包和部署它。
它能做什么
该技能涵盖几种部署场景：
- 部署到 Agent Runtime。 这是专为智能体构建的托管部署目标。它处理自动扩展、通过
VertexAiSessionService进行会话状态持久化，并支持智能体身份和通过 PSC 接口进行私有 VPC 连接等功能。 - 部署到 Cloud Run。 适用于需要更多基础设施控制、事件驱动触发器（Pub/Sub、Eventarc）或自定义网络的团队。Cloud Run 支持完全可配置的扩展、直接 VPC 出口和 IAP。
- 部署到 GKE。 适用于需要完全 Kubernetes 控制的团队，包括 HPA、VPA、节点自动配置和自定义网络。此选项设置复杂度最高，但提供最大的灵活性。
- 管理密钥。
--secrets标志允许你从 Secret Manager 将密钥作为环境变量注入到部署的服务中。 - 配置 CI/CD。 该技能包含使用
agents-cli infra cicd设置完整 CI/CD 管道的指南，包括运行器比较、Workload Identity Federation 身份验证和管道阶段配置。 - 处理回滚。 因为部署是版本化的，如果部署引入了问题，你可以回滚到之前的版本。
选择部署目标
该技能提供了一个决策矩阵来帮助你在 Agent Runtime、Cloud Run 和 GKE 之间做出选择。以下是简化版本：
- Agent Runtime 最适合你想要托管基础设施且运营开销最小的情况。它支持 Python 智能体，具有原生会话状态管理，并且在空闲时不计费。但是，它不支持 Pub/Sub 或 Cloud Scheduler 等事件驱动触发器。
- Cloud Run 最适合你需要事件驱动工作负载、自定义网络或更多扩展行为控制的情况。它原生支持 Pub/Sub 和 Eventarc 触发器。
- GKE 最适合你需要完全 Kubernetes 控制、想要在自定义容器中运行非 Python 智能体，或者有现有 Kubernetes 基础设施想要复用的情况。
如果你的智能体需要 OAuth 2.0 用户同意流程（例如，代表用户访问 Google Drive 或 Calendar），推荐使用带有 Gemini Enterprise 的 Agent Runtime。Cloud Run 目前不支持托管的 OAuth 流程。
部署工作流如何运作
使用 agents-cli 的部署过程遵循一个结构化的序列。理解这个序列可以帮助你避免最常见的失败模式。
步骤 1：确保你的项目已准备就绪
如果你的项目没有通过脚手架添加部署支持，你需要先添加它：
agents-cli scaffold enhance . --deployment-target <target>
将 <target> 替换为 agent_runtime、cloud_run 或 gke。这会为你的项目添加必要的 Dockerfile、Terraform 配置和部署元数据。
步骤 2：获取人工批准
该技能明确要求在部署前获得人工批准。这是一个安全机制。CLI 会提示你：
"评估分数达到阈值且测试通过。准备好部署到开发环境了吗？"
你必须等待明确的批准才能继续。这可以防止意外部署，并确保有人审查了智能体的就绪状态。
步骤 3：运行部署命令
agents-cli deploy
这个单一命令处理构建容器镜像、将其推送到 Artifact Registry、配置部署目标以及启动服务。你可以传递标志来自定义部署：
--project指定 GCP 项目 ID--region指定部署区域--service-account指定服务账户邮箱--secrets将密钥作为环境变量注入--update-env-vars设置额外的环境变量
步骤 4：验证部署
部署后，验证智能体是否正常运行。该技能包含针对每个部署目标的测试说明，包括 curl 示例和负载测试指南。
处理超时
Agent Runtime 部署可能需要 5-10 分钟，并且可能超过命令超时时间。如果部署命令被取消或超时，部署会在服务端继续。你可以使用以下命令检查进度：
agents-cli deploy --status
每 60 秒轮询一次，直到它报告完成或失败。
何时不使用此技能
google-agents-cli-deploy 技能有明确的边界。它不是适合所有情况的正确工具：
- 非 ADK 智能体。 如果你的智能体不是使用 Google Agent Development Kit 构建的，这个工具将无法工作。它依赖于 ADK 特定的项目结构和元数据。
- API 代码模式。 如果你需要帮助编写智能体代码，请改用
google-agents-cli-adk-code技能。 - 评估。 如果你需要评估智能体性能，请使用
google-agents-cli-eval技能。 - 项目脚手架。 如果你需要从头创建一个新的 ADK 项目，请使用
google-agents-cli-scaffold技能。 - 可观测性。 如果你需要 Cloud Trace、请求-响应日志记录或 BigQuery 分析，请使用
google-agents-cli-observability技能。
该技能也不直接处理使用 BigQuery Remote Function 触发器的批量推理或 Pub/Sub 事件驱动模式。对于这些，你需要查看 google-agents-cli-adk-code 技能及其参考文档。
设置上下文和先决条件
在使用此技能之前，你需要：
- 安装
agents-cli。 该工具通过uv tool install google-agents-cli安装。如果你没有uv，你需要先从 uv 文档 安装它。 - 一个 ADK 项目。 你的项目应该已经通过脚手架添加了部署支持。如果没有，请使用脚手架技能来添加。
- GCP 凭据。 你需要经过身份验证的 GCP 凭据，并具有部署到你选择的目标（Cloud Run、GKE 或 Agent Runtime）的权限。
- 一个 GCP 项目。 你需要一个启用了必要 API 的项目（Cloud Run、GKE、Artifact Registry 等，具体取决于你的目标）。
可选：单项目基础设施设置
如果你需要在单个 GCP 项目中配置基础设施而不使用 CI/CD（服务账户、IAM 绑定、遥测资源、Artifact Registry），你可以运行：
agents-cli infra single-project
这是可选的。agents-cli deploy 命令不需要它即可工作。如果你需要可观测性功能或想在进入生产之前在单个项目中测试基础设施，请使用它。
请注意，agents-cli deploy 不会自动使用 Terraform 创建的服务账户。你需要通过 --service-account SA_EMAIL 显式传递它。
安全信号和仓库健康状况
在评估是否采用此技能时，请考虑以下信号：
- 仓库所有者。 该仓库由 Google 维护，这提供了一定程度的责任感和长期支持。
- 许可证。 该技能在 Apache-2.0 许可证下发布，这是一个宽松的开源许可证。
- 星标和社区。 该仓库拥有超过 3,000 颗星，表明社区活跃度很高。
- 安全级别。 该技能被评为低风险，意味着它不需要超出部署所需的提升权限或对敏感资源的访问。
- 版本。 当前版本是 0.5.1，表明该工具仍在发展中。预计未来版本会有破坏性变更。
使用前需要检查的内容
在将此技能纳入生产工作流之前，请检查：
- 参考文档。 该技能包含针对每个部署目标的详细参考文件（
cloud-run.md、agent-runtime.md、gke.md）。阅读与你的目标相关的文件。 - Terraform 模式。 如果你计划自定义基础设施，请查看
terraform-patterns.md以了解 IAM、状态管理和资源导入指南。 - CI/CD 管道文档。 如果你计划设置自动化部署，请查看
cicd-pipeline.md以了解运行器比较、WIF 身份验证和管道阶段配置。 - 测试文档。 查看
testing-deployed-agents.md以获取针对你的部署目标的测试说明。 - 你团队的 Kubernetes 专业知识。 如果你正在考虑 GKE，请确保你的团队具备必要的 Kubernetes 知识。GKE 的设置复杂度最高。
实际示例：部署到 Cloud Run
以下是将 ADK 智能体部署到 Cloud Run 的简化示例：
-
确保你的项目具有部署支持：
agents-cli scaffold enhance . --deployment-target cloud_run -
审查
deployment/中生成的 Dockerfile 和 Terraform 配置。 -
获取部署的人工批准。
-
部署：
agents-cli deploy --project my-gcp-project --region us-central1 --service-account agent-sa@my-gcp-project.iam.gserviceaccount.com --secrets API_KEY=my-secret:latest -
验证部署：
curl https://my-service-abc123-uc.a.run.app/health -
如果出现问题，检查部署状态：
agents-cli deploy --status
总结
将 AI 智能体部署到生产环境是一个真正的工程挑战。google-agents-cli-deploy 技能为 ADK 智能体提供了一种结构化方法，涵盖 Agent Runtime、Cloud Run 和 GKE 部署目标。它在部署前强制执行人工批准，支持密钥管理，并包含 CI/CD 管道指南。
它不是一个通用解决方案。它只适用于 ADK 项目，不处理智能体代码或评估，并且 GKE 路径需要 Kubernetes 专业知识。但如果你的团队正在使用 Google Agent Development Kit 构建智能体，并且需要一个能够减少手动错误并强制执行最佳实践的部署工作流，那么它值得检查。
首先阅读技能页面和你选择的部署目标的参考文档。在将其用于生产工作负载之前，先在非关键项目上测试它。