AI Skills
google-agents-cli-deploy

google-agents-cli-deploy

热门

当用户想要“部署 Agent”、“部署 ADK Agent”、“配置 CI/CD”、“配置 Secret 密钥”、“排查部署故障”，或需要关于 Agent Runtime、Cloud Run 或 GKE 部署目标的指导时，应使用此 Skill。 涵盖部署工作流、服务账号、版本回滚和生产基础设施。 属于 Google ADK (Agent Development Kit) Skill 套件的一部分。 切勿用于 API 代码模式（请使用 google-agents-cli-adk-code）、评估测试（请使用 google-agents-cli-eval）或项目脚手架搭建（请使用 google-agents-cli-scaffold）。

3081Star
487Fork
更新于 2026/6/22
获取 Skill源代码

相关 Skills

cmux-backend2.5万tmux39万sherpa-onnx-tts38万
SKILL.md
只读
名称
google-agents-cli-deploy
描述

当用户想要“部署 Agent”、“部署 ADK Agent”、“配置 CI/CD”、“配置 Secret 密钥”、“排查部署故障”，或需要关于 Agent Runtime、Cloud Run 或 GKE 部署目标的指导时，应使用此 Skill。 涵盖部署工作流、服务账号、版本回滚和生产基础设施。 属于 Google ADK (Agent Development Kit) Skill 套件的一部分。 切勿用于 API 代码模式（请使用 google-agents-cli-adk-code）、评估测试（请使用 google-agents-cli-eval）或项目脚手架搭建（请使用 google-agents-cli-scaffold）。

ADK 部署指南

依赖项： agents-cli (uv tool install google-agents-cli) — 如有需要，请先安装 uv。

本指南全程优先推荐使用 agents-cli 命令——它们将 Terraform、Docker 与部署流程打包集成到了一个经过测试的流水线中。如果你的项目尚未搭建脚手架，请先参考 /google-agents-cli-scaffold 添加部署支持。

参考文件

如需了解更详细的信息，请查阅 references/ 目录下的参考文件：

  • cloud-run.md — 弹性伸缩默认配置、Dockerfile、会话类型、网络配置
  • agent-runtime.md — deploy.py CLI、AdkApp 模式、Terraform 资源、部署元数据、CI/CD 差异
  • gke.md — GKE Autopilot 集群、Kubernetes 清单 (Manifests)、Workload Identity、会话类型、网络配置
  • terraform-patterns.md — 自定义基础设施、IAM 权限、状态管理、导入已有资源
  • batch-inference.md — BigQuery 远程函数 (Remote Function) 触发器；Pub/Sub / Eventarc 相关内容请参阅 /google-agents-cli-adk-code
  • cicd-pipeline.md — 完整的 CI/CD 流水线配置、infra cicd 参数标志、Runner 选型对比、WIF 认证、流水线阶段
  • testing-deployed-agents.md — 针对不同部署目标的测试说明、curl 示例、压力测试

可观测性： 关于 Cloud Trace、提示词与响应日志记录、BigQuery Analytics 以及第三方集成，请参阅 /google-agents-cli-observability Skill。

部署目标选型矩阵

根据你的业务需求选择合适的部署目标：

评估维度 Agent Runtime Cloud Run GKE
支持语言 Python Python Python（+ 通过自定义容器支持其他语言）
弹性伸缩 托管式自动扩缩容（可配置最小/最大实例数、并发度） 完全可控（实例数上下限、并发度、CPU 分配） 完整的 Kubernetes 伸缩能力（HPA、VPA、节点自动扩容）
网络配置 支持 VPC-SC 与 PSC-I（通过网络附加件实现私有 VPC 互通） 完整 VPC 支持、直接 VPC 出站、IAP、入站规则 完整的 Kubernetes 网络生态
会话状态 原生 VertexAiSessionService（托管持久化） 内存存储 (开发环境)、Cloud SQL 或 Agent Platform Sessions 后端 内存存储 (开发环境)、Cloud SQL 或 Agent Platform Sessions 后端
批处理/事件处理 不支持 原生触发器端点 (Pub/Sub, Eventarc)；参见 /google-agents-cli-adk-code 自定义实现 (Kubernetes Jobs, Pub/Sub)
计费模式 vCPU 时长 + 内存时长（闲置时不计费） 按实例运行秒数计费 + 最小实例成本 节点池成本（常驻或按需扩容）
配置复杂度 较低（托管式，专门针对 Agent 优化） 中等（需配置 Dockerfile、Terraform、网络） 较高（需具备 Kubernetes 专业知识）
适用场景 托管基础设施、运维成本低 自定义架构、事件驱动型工作负载 需完全掌控 Kubernetes 环境

请询问用户哪种部署目标符合其需求。每种目标都是具备不同权衡利弊的合格生产环境选项。

产品名称变更说明： “Agent Engine” / “Vertex AI Agent Engine” 现已更名为 Agent Runtime。使用 --deployment-target agent_runtime 参数。

常驻 / 定时 / 事件驱动型 Agent： Agent Runtime 不支持 Pub/Sub、Eventarc 或 Cloud Scheduler 触发器。对于此类工作负载，推荐使用 Cloud Run（推荐）或 GKE。关于 trigger_sources 模式，请参阅 /google-agents-cli-adk-code（references/adk-python.md 第“12. 事件驱动 / 常驻 Agent”节）。

OAuth / 用户授权型 Agent： 如果 Agent 需要 OAuth 2.0 用户授权（例如访问 Google Drive、Calendar 或其他用户作用域的 API），请使用 Agent Runtime 配合 Gemini Enterprise。Cloud Run 目前暂不支持托管 OAuth 授权流。请参考 /google-agents-cli-workflow 阶段 1 中的 adk-ae-oauth 示例。

部署到开发环境 (Dev)

部署工作流

任务追踪： 部署过程包含多个连续步骤（基础设施搭建、CI/CD 配置、部署执行、结果验证）。建议使用任务清单来追踪进度——跳过任意一步都可能导致后续出现难以排查的故障。

  1. 如果属于原型阶段（未指定部署目标），请先增强配置：agents-cli scaffold enhance . --deployment-target <target>
  2. 通知用户：“评估得分符合预设阈值且测试已通过。是否开始部署到开发环境 (dev)？”
  3. 等待用户的明确确认
  4. 获得批准后执行：agents-cli deploy

Agent Runtime 超时恢复机制： Agent Runtime 的部署可能需要 5 到 10 分钟，有时会超出命令超时限制。如果部署命令被取消或超时，云端的部署任务仍会继续进行。运行 agents-cli deploy --status 查看进度——建议每 60 秒轮询一次，直至返回成功或失败状态。

重要提示：未经用户明确批准，绝对不要擅自运行 agents-cli deploy。

切勿在部署前运行 agents-cli infra single-project。 它不是前置依赖——agents-cli deploy 本身即可独立运行。仅当用户需要可观测性功能（提示词/响应日志、BigQuery 分析）时才需单独运行该命令——详情参阅 /google-agents-cli-observability。

单项目基础设施搭建（可选 — 高级选项）

agents-cli infra single-project 会运行 deployment/terraform/single-project/ 目录下的 terraform apply。该命令用于在不借助 CI/CD 的情况下直接创建单项目 GCP 基础设施（服务账号、IAM 绑定、遥测资源、Artifact Registry）。在上线生产环境前进行单项目功能测试时也非常有用。这不是部署的必要前置条件。

# 可选 — 在单个 GCP 项目中创建基础设施
agents-cli infra single-project

注意： agents-cli deploy 不会自动使用 Terraform 创建的 app_sa。对于 Agent Runtime 部署目标，需通过 agents-cli deploy --service-account SA_EMAIL 或 uv run -m app.app_utils.deploy --service-account SA_EMAIL 手动传入服务账号。

部署 Flag 参数参考表

Flag 参数 说明描述 适用部署目标
--project GCP 项目 ID 全部
--region GCP 区域 (Region) 全部
--service-account 部署 Agent 对应的服务账号邮箱 全部
--service-name 覆盖部署的服务名称（Cloud Run 服务名或 Agent Runtime 显示名称）；默认使用项目名称。如果进行了覆盖，建议同步更新 Terraform 与 CI 配置（如有），因为它们默认根据项目名称命名资源。GKE 不支持此参数（名称完全由 Terraform 管理）。 Agent Runtime, Cloud Run
--secrets 以逗号分隔的 ENV=SECRET 或 ENV=SECRET:VERSION 密钥键值对 Agent Runtime, Cloud Run
--update-env-vars 以逗号分隔的 KEY=VALUE 环境变量 Agent Runtime, Cloud Run
--agent-identity 启用 Agent 身份标识 (Agent Identity)（预览版） Agent Runtime
--network-attachment PSC Interface 的网络附加件资源名称（用于启用私有 VPC 连通性） Agent Runtime
--dns-peering-domain DNS 对等连接域名后缀，例如 my-internal.corp.（需结合 --network-attachment 使用） Agent Runtime
--dns-peering-project 托管 DNS 对等连接 Cloud DNS 托管区域的目标项目 ID（需结合 --network-attachment 使用） Agent Runtime
--dns-peering-network 目标项目中用于 DNS 对等连接的 VPC 网络名称（需结合 --network-attachment 使用） Agent Runtime
--memory 内存上限限制（默认值：4Gi） Agent Runtime, Cloud Run
--cpu CPU 上限限制（默认值：1） Agent Runtime, Cloud Run
--min-instances 最小实例数（默认值：1） Agent Runtime, Cloud Run
--max-instances 最大实例数（默认值：10） Agent Runtime, Cloud Run
--concurrency 每个容器的并发请求数（默认值：8；详见部署资源规格调优） Agent Runtime, Cloud Run
--num-workers 每个容器的 Worker 进程数（默认值：1） Agent Runtime
--port 容器端口 Cloud Run
--iap 启用 Identity-Aware Proxy (IAP) Cloud Run
--image 容器镜像 URI（跳过源码构建步骤） Cloud Run, GKE
--no-wait 启动部署任务后立即返回，不阻塞等待 Agent Runtime, Cloud Run
--status 检查带有 --no-wait 参数的后台部署任务状态 Agent Runtime, Cloud Run
--list 列出已有部署并退出 全部
--dry-run / -n 仅打印将要执行的命令，不实际运行 全部
--no-confirm-project 跳过项目确认提示 全部

运行 agents-cli deploy --help 可查看完整的 Flag 参数选项。

高级 Cloud Run 部署用法： 如果需要使用 agents-cli Flag 未暴露的功能，可以使用 --dry-run（或 -n）打印出完整的 gcloud 命令，将其复制并根据需求添加额外参数。

项目自动确认： 如果项目 ID 是自动解析的（未通过 --project 手动传入），该命令在交互模式下会提示用户确认。由于 Agent 通常在非交互模式下运行，如果你依赖自动项目解析，必须传入 --no-confirm-project 才能正常继续。

部署资源规格调优

默认配置（Agent Runtime、Cloud Run 以及生成的 service.tf 保持一致）：--cpu 1，--memory 4Gi，--num-workers 1，--concurrency 8，--min-instances 1，--max-instances 10。

这些参数紧密联动——调整时需同步按比例扩缩：

  • Workers 数量 = vCPU 核心数。 每个 Worker 都是一个受 GIL 限制的单核进程，因此当增加 --cpu 时应同步调大 --num-workers（例如 --cpu 4 → --num-workers 4），否则付费购买的 CPU 核心会被浪费闲置。
  • 内存大小决定了并发上限。 每个并发请求在等待模型响应期间，都会将其完整的运行时数据（上下文窗口、历史记录、RAG 分块、响应缓冲区）保留在内存中，因此内存峰值 ≈ 基础内存 + 并发数 × 单请求内存。内存（而非 CPU）通常是最先达到的瓶颈，在不增加 --memory 的情况下盲目调高 --concurrency 是导致 OOM（内存溢出）的主要原因。
  • 默认并发设置偏保守。 一个异步 Worker 在等待模型返回时可以同时处理多个并发请求，但由于每个请求的内存开销因 Agent 业务而异，默认值 8 能有效保护高内存占用（如 RAG/多模态）的 Agent。轻量级 Agent 在经过压力测试后，可将其上调至 16–32+。参考文档：异步 Worker 未充分利用的说明。
# 实现 4 倍吞吐量：成比例调整所有参数，而非仅改动单个选项
agents-cli deploy --cpu 4 --num-workers 4 --concurrency 16 --memory 16Gi

利用脚手架生成的压测工具调优（位于 tests/load_test/，可在本地或 CI/CD 预发布流水线中运行）：施加负载压力，观察最大延迟以及内存/OOM 重启情况，然后进行针对性微调——若最大延迟偏高 → 调高并发数（同时增加 Worker/CPU）；若发生 OOM → 增加内存或降低并发数。

--num-workers 仅适用于 Agent Runtime（Cloud Run 内部只运行单个 uvicorn 进程）。在 GKE 上这些 Flag 参数会被拒绝——请通过 deployment/terraform/ 目录下的 Terraform 清单与 HorizontalPodAutoscaler 重新配置规格。

生产环境部署 — CI/CD 流水线

关于完整的 CI/CD 流水线配置指南——包含前置条件、infra cicd 参数标志、Runner 选型对比、WIF 身份验证、流水线阶段以及生产环境部署...

<!-- 翻译批次截断；源文件全文在此处继续 -->