企业官网建设流程全解析

agents-cli 部署实战指南：将 AI Agent 从开发环境一键部署到 Cloud Run、GKE 与 Agent Runtime

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli

<output_article>（占位，防止解析错误）

agents-cli 部署实战指南：将 AI Agent 从开发环境一键部署到 Cloud Run、GKE 与 Agent Runtime

本文是 Google agents-cli 部署模块的完整实战指南。你将学会区分"基础设施（infra）"与"部署（deploy）"两个阶段，掌握agents-cli deploy的完整命令面：如何在开发环境完成首次部署、如何针对 Agent Runtime / Cloud Run / GKE 三种部署目标使用各自的专属参数，以及如何用--dry-run、--no-wait、--status、--list等运维参数管理部署生命周期。文章基于 部署文档 展开，并深入 deploy 命令源码 与 Agent Runtime 部署实现，讲清每个参数背后的真实执行路径与默认值。

先分清两件事：Infrastructure 与 Deployment

在动手部署之前，必须理解 agents-cli 把"上云"拆成了两个独立阶段，二者职责不同、前后衔接：

• Infrastructure（agents-cli infra）：负责"搭台"。它为你的 Agent 预置所需的云资源——服务账号、IAM 绑定、API 启用、遥测存储桶（telemetry buckets）以及 Terraform state。它把舞台搭好，但不运行你的 Agent。
• Deployment（agents-cli deploy）：负责"唱戏"。它把你的 Agent 代码放到已经预置好的基础设施上——构建容器、推送到镜像仓库、启动服务。

典型流程是：先预置基础设施，再在其上部署。二者由 ProjectConfig 配置模型 中的deployment_target字段串联起来：agents-cli infra按目标生成 Terraform 资源，agents-cli deploy则按同一目标分发到对应的部署执行器。

从 deploy 命令入口 可以看到，agents-cli deploy是一个基于 Click 构建的子命令，注册了 30 多个选项；命令体内部通过deployment_target分发到三条独立执行路径：

agent_runtime → Agent Runtime 部署（全托管） cloud_run → gcloud run deploy（容器跑在 Cloud Run 上） gke → terraform + docker build + kubectl apply

提示：想了解观测性（提示词-响应日志、内容日志）如何开启，请在部署完成后运行agents-cli infra single-project，Terraform 会预置遥测资源并把你的服务更新为使用它们，详见 观测性指南。

部署到开发环境：最快路径

对于本地迭代，最快的一条部署路径只需两条命令：

1. 设置开发项目：

gcloud config set project YOUR_DEV_PROJECT_ID

2. 部署 Agent：

agents-cli deploy

这条命令会读取agents-cli-manifest.yaml中create_params下的deployment_target（配置读取逻辑见 ProjectConfig.from_dict），然后按目标分发到对应流程：

部署目标在创建项目时设定：

agents-cli create my-agent -d cloud_run # 或 agent_runtime、gke

如何修改已有项目的部署目标

已创建的项目想更换部署目标，用scaffold enhance：

agents-cli scaffold enhance -d cloud_run

运行agents-cli scaffold enhance --help查看全部可用选项。

部署后如何验证

agents-cli deploy --list # 列出已有部署 agents-cli deploy --status # 检查部署状态

这两个子参数的分发逻辑同样按目标分流：Agent Runtime 走 Agent Platform SDK 的 agent_engines.list、Cloud Run 走gcloud run services list、GKE 走kubectl get deployments（见源码实现），最终都以富文本表格形式输出。

无 manifest 时的兜底行为

从 源码 可以看出，部署还支持一种"无 manifest"模式：当当前目录及其父目录都找不到agents-cli-manifest.yaml时，只要显式传入--deployment-target也能部署（例如从 CI 或预构建产物发起）。此时 CLI 会打印警告，说明正在使用的默认值——包括解析出的服务名、agent 目录和构建目录（当前工作目录）。如果既不传--deployment-target又找不到 manifest，命令会直接报错并提示先agents-cli create my-agent。

另一个与项目状态强相关的校验是 require_deployment_target：当 manifest 中deployment_target为none或为空时，deploy 会拒绝执行并提示先运行agents-cli scaffold enhance为项目添加部署支持。

部署目标一：Agent Runtime（全托管）

选择方式：agents-cli create my-agent -d agent_runtime，或在agents-cli-manifest.yaml中设置create_params.deployment_target: agent_runtime。

Agent Runtime 是全托管运行时：你只需提供Dockerfile（scaffold 时会自动生成），Agent Engine 负责构建并运行容器——不需要自己运维集群或服务：

agents-cli deploy --project my-gcp-project --region us-east1

Agent Runtime 始终从项目根目录的 Dockerfile 构建镜像，因此不支持传预构建的--image，但支持传 Docker 构建参数和容器端口：

agents-cli deploy --build-args KEY=VALUE --port 8080

异步部署与状态查询

Agent Runtime 的部署是一次长时操作（create/update 会持续几分钟），CLI 为此内置了操作持久化机制：

agents-cli deploy --no-wait # 立即启动并返回 agents-cli deploy --status # 之后随时查看进度

从 部署操作持久化实现 可以看到原理：启动部署时，CLI 把长时操作（LRO）的名称、项目、位置等信息写入项目根目录的deployment_metadata.json的pending_operation字段；--status读取该字段并轮询后端操作状态，查询完成后会自动清除。即使--no-wait后命令被中断，也可以用--status恢复查询。

Agent Runtime 专属的进阶参数

从 deploy 命令选项定义 可以确认，以下参数仅对 Agent Runtime 生效（对其他目标会直接报错拒绝）：

这些参数在 deploy_agent_runtime 函数 中被组装进AgentEngineConfig，最终通过 Agent Platform SDK 的 create/update 操作提交。

Agent Runtime 的环境变量处理

源码 _build_runtime_env_vars 揭示了环境变量的完整优先级与默认行为：

• 优先级（从高到低）：--update-env-vars/--set-secrets> 项目根目录.env> 可覆盖的默认值。
• GOOGLE_CLOUD_PROJECT是保留变量：Agent Runtime 平台自己注入，用户在.env或 flag 中设置会被忽略并告警。
• 默认注入AGENT_VERSION（从 pyproject.toml 等解析的版本，A2A agent card 运行时会读取）。
• 未配置GEMINI_API_KEY/GOOGLE_API_KEY时，默认使用 Vertex AI（GOOGLE_GENAI_USE_VERTEXAI=true、GOOGLE_CLOUD_LOCATION=global）。
• 默认开启遥测：GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true。
• 遵循 fail-closed 原则：ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS默认false，避免在 span 中捕获消息内容。

部署目标二：Cloud Run

选择方式：agents-cli create my-agent -d cloud_run，或在 manifest 中设置create_params.deployment_target: cloud_run。

从源码构建容器并部署为 Cloud Run 服务：

agents-cli deploy --project my-gcp-project --region us-east1

覆盖资源限制：

agents-cli deploy --memory 8Gi --port 8080

部署预构建镜像（跳过源码构建）：

agents-cli deploy --image gcr.io/my-project/my-agent:v1

提示：如果你需要agents-cli参数没有暴露的 Cloud Run 高级特性，用--dry-run（或-n）打印完整gcloud命令，复制后自行追加参数即可。

Cloud Run 执行路径详解

从 cmd_deploy 的 cloud_run 分支 可以还原真实的gcloud命令组装过程：

1. 命令基底：gcloud run deploy <service_name>，追加--project、--region；有--image用--image，否则用--source .从源码构建。
2. 默认值策略（create 与 update 不同）：CLI 会先通过 Cloud Run Admin API v2 的 REST GET 判断服务是否已存在（见 _cloud_run_service_exists，比gcloud run services describe快约 2 秒）。创建时应用保守默认值，更新时不传未指定的 flag，让 gcloud 保留线上值。
3. 固定注入的安全默认：--no-allow-unauthenticated（默认要求认证）与--no-cpu-throttling。
4. 环境变量合并：--update-env-vars优先 > 项目.env> 默认值；自动注入AGENT_VERSION和APP_URL（格式https://<service>-<projectNumber>.<region>.run.app），并默认ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false。
5. Secret 挂载：--secrets ENV=SECRET[:VERSION]会转成--update-secrets（合并语义，而非会丢弃未列出项的--set-secrets）；若同一变量名同时出现在明文环境变量和 secret 中会报错。
6. 标签：用户标签与保留的created-by: agents-cli合并后通过--update-labels注入。
7. IAM 传播的自动重试：首次创建后，跨项目拉取镜像常因 IAM 权限传播出现临时 403（错误信息形如 "permissions might take a few minutes to propagate"）。CLI 用指数退避（5s→10s→20s→30s 封顶，带全抖动）最多重试 600 秒（见 _CLOUD_RUN_DEPLOY_MAX_TIME 等常量），真正的权限配置错误则快速失败。

所有KEY=VALUE参数在回显时都会经过 redact_command 脱敏，值以***显示，避免.env中的密钥泄漏到终端或 CI 日志。

部署目标三：GKE

选择方式：agents-cli create my-agent -d gke，或在 manifest 中设置create_params.deployment_target: gke。

通过 Terraform 和 kubectl 部署到 GKE 集群：

agents-cli deploy --cluster-name my-cluster --project my-gcp-project

从 GKE 部署实现 可以看到完整的七步线性流程：

1. （本地开发模式）定向 Terraform apply：对 14 个目标资源（GKE 集群、Artifact Registry 仓库、NAT、防火墙、服务账号、Workload Identity 绑定、Kubernetes 的 namespace/service account/deployment/service/HPA/PDB 等）执行terraform apply -auto-approve -input=false。
2. 获取集群凭据：gcloud container clusters get-credentials <cluster_name> --region <region>。
3. （本地开发模式）构建并推送镜像：通过 Cloud Build 异步提交（--async）再轮询builds describe，避免 gcloud 默认日志流在 VPC-SC 等环境下误报失败。
4. 滚动更新镜像：kubectl set image deployment/<service> <service>=<image>。
5. 注入运行时环境变量：AGENT_VERSION、--update-env-vars及APP_URL（默认http://<service-ip>:8080）。
6. 等待滚动完成：kubectl rollout status ... --timeout=600s。
7. 输出摘要：显示内部服务 IP，并提示kubectl port-forward svc/<service> 8080:8080 -n <service>用于本地访问。

两种模式与 GKE 参数限制

GKE 部署支持两种模式：CI/CD 模式（传入--image，跳过 Terraform 与本地构建）和本地开发模式（不传--image，走完整 Terraform + Cloud Build 流程）。

GKE 的资源命名由 Terraform 的var.project_name决定，因此：

• 不支持--service-name（会报错，避免 kubectl 侧引用指向 Terraform 从未创建的资源）；
• 不支持--cpu / --memory / --min-instances / --max-instances / --concurrency（这些应由 Terraform 与 HorizontalPodAutoscaler 配置，见deployment/terraform/下的 HPA 定义）；
• 不支持--labels（GKE 资源标签由 Terraform 管理）；
• 不支持--no-wait和--status。

通用参数：所有目标都适用的部署开关

以下参数在所有部署目标下行为一致（见 cmd_deploy 源码）：

各目标的默认机器规格

所有可调大小的参数都共享 _utils.py 中的默认常量（生成的 Terraformservice.tf会手工同步这些值）：

注意：生产部署建议走 Terraform 路径（其service.tf将min_instances固定为 1 以避免冷启动），或显式传--min-instances。

部署目标配置的来源：agents-cli-manifest.yaml

deployment_target的最终来源是项目根目录的agents-cli-manifest.yaml。从 模板文件 可以看到其结构：

name: '<项目名>' acli_version: '<scaffold 时的 CLI 版本>' agent_directory: 'app' region: 'us-east1' base_template: 'adk' generated_at: '<生成时间>' language: 'python' create_params: deployment_target: '<agent_runtime | cloud_run | gke | none>' session_type: 'none' cicd_runner: 'skip' agent_gateway: false agent_guidance_filename: 'GEMINI.md'

ProjectConfig 读取逻辑 会优先读取agents-cli-manifest.yaml；找不到时回退读取旧的pyproject.toml中的[tool.agents-cli]段（此时会提示运行agents-cli scaffold upgrade迁移），两者都没有则返回默认配置（deployment_target: none，触发上文提到的拒绝校验）。

下一步：CI/CD 与生产环境

部署到开发环境只是第一步。完整生产化路径还包括：

• CI/CD 与生产部署——搭建"PR 触发测试 → 合入 main 部署 staging → 人工审批上生产"的自动化流水线；
• 观测性——监控已部署的 Agent。

生产流水线部署的是 staging 环境已验证过的同一容器镜像，并支持 Cloud Run 与 GKE 两种部署目标、Cloud Build 与 GitHub Actions 两种 runner 的自动检测。部署完成后，还可以用agents-cli publish gemini-enterprise把 Agent 注册到 Gemini Enterprise（运行--help查看全部选项）。 </output_article>

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli