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-clioutput_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 把上云拆成了两个独立阶段二者职责不同、前后衔接Infrastructureagents-cli infra负责搭台。它为你的 Agent 预置所需的云资源——服务账号、IAM 绑定、API 启用、遥测存储桶telemetry buckets以及 Terraform state。它把舞台搭好但不运行你的 Agent。Deploymentagents-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-projectTerraform 会预置遥测资源并把你的服务更新为使用它们详见 观测性指南。部署到开发环境最快路径对于本地迭代最快的一条部署路径只需两条命令1. 设置开发项目gcloud config set project YOUR_DEV_PROJECT_ID2. 部署 Agentagents-cli deploy这条命令会读取agents-cli-manifest.yaml中create_params下的deployment_target配置读取逻辑见 ProjectConfig.from_dict然后按目标分发到对应流程deployment_target实际发生什么agent_runtimeAgent Runtime 部署全托管cloud_rungcloud beta run deploy容器部署到 Cloud RungkeTerraform Docker 构建 kubectl apply部署目标在创建项目时设定agents-cli create my-agent -d cloud_run # 或 agent_runtime、gke如何修改已有项目的部署目标已创建的项目想更换部署目标用scaffold enhanceagents-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 是全托管运行时你只需提供Dockerfilescaffold 时会自动生成Agent Engine 负责构建并运行容器——不需要自己运维集群或服务agents-cli deploy --project my-gcp-project --region us-east1Agent Runtime 始终从项目根目录的 Dockerfile 构建镜像因此不支持传预构建的--image但支持传 Docker 构建参数和容器端口agents-cli deploy --build-args KEYVALUE --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 生效对其他目标会直接报错拒绝参数说明--agent-identity启用 Agent Identity预览功能。首次部署时创建独立身份主体并自动授予 6 个 IAM 角色见 setup_agent_identity。注意身份类型创建后不可更改--update-only仅更新已有部署若目标不存在则失败而不是创建避免覆盖由 Terraform 或平台模板管理的配置--build-args KEYVALUE传给容器镜像构建的参数逗号分隔--network-attachmentPSC 网络挂载点资源名启用私有 VPC 连接。格式projects/PROJECT/regions/REGION/networkAttachments/NAME--dns-peering-domain / --dns-peering-project / --dns-peering-networkDNS peering 三项配置必须与--network-attachment一起使用且三者齐备--agent-gateway-egress / --agent-gateway-ingress将 Agent 的出站/入站流量路由到已有 Agent Gateway。传空值表示解绑不传表示保持现状。出站网关要求项目以--agent-gatewayscaffold用于 CA 信任配置这些参数在 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 AIGOOGLE_GENAI_USE_VERTEXAItrue、GOOGLE_CLOUD_LOCATIONglobal。默认开启遥测GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRYtrue。遵循 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命令组装过程命令基底gcloud run deploy service_name追加--project、--region有--image用--image否则用--source .从源码构建。默认值策略create 与 update 不同CLI 会先通过 Cloud Run Admin API v2 的 REST GET 判断服务是否已存在见 _cloud_run_service_exists比gcloud run services describe快约 2 秒。创建时应用保守默认值更新时不传未指定的 flag让 gcloud 保留线上值。固定注入的安全默认--no-allow-unauthenticated默认要求认证与--no-cpu-throttling。环境变量合并--update-env-vars优先 项目.env 默认值自动注入AGENT_VERSION和APP_URL格式https://service-projectNumber.region.run.app并默认ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANSfalse。Secret 挂载--secrets ENVSECRET[:VERSION]会转成--update-secrets合并语义而非会丢弃未列出项的--set-secrets若同一变量名同时出现在明文环境变量和 secret 中会报错。标签用户标签与保留的created-by: agents-cli合并后通过--update-labels注入。IAM 传播的自动重试首次创建后跨项目拉取镜像常因 IAM 权限传播出现临时 403错误信息形如 permissions might take a few minutes to propagate。CLI 用指数退避5s→10s→20s→30s 封顶带全抖动最多重试 600 秒见 _CLOUD_RUN_DEPLOY_MAX_TIME 等常量真正的权限配置错误则快速失败。所有KEYVALUE参数在回显时都会经过 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 部署实现 可以看到完整的七步线性流程本地开发模式定向 Terraform apply对 14 个目标资源GKE 集群、Artifact Registry 仓库、NAT、防火墙、服务账号、Workload Identity 绑定、Kubernetes 的 namespace/service account/deployment/service/HPA/PDB 等执行terraform apply -auto-approve -inputfalse。获取集群凭据gcloud container clusters get-credentials cluster_name --region region。本地开发模式构建并推送镜像通过 Cloud Build 异步提交--async再轮询builds describe避免 gcloud 默认日志流在 VPC-SC 等环境下误报失败。滚动更新镜像kubectl set image deployment/service serviceimage。注入运行时环境变量AGENT_VERSION、--update-env-vars及APP_URL默认http://service-ip:8080。等待滚动完成kubectl rollout status ... --timeout600s。输出摘要显示内部服务 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 定义不支持--labelsGKE 资源标签由 Terraform 管理不支持--no-wait和--status。通用参数所有目标都适用的部署开关以下参数在所有部署目标下行为一致见 cmd_deploy 源码参数说明--projectGCP 项目 ID。未显式传入时从gcloud config解析并会弹出确认提示可加--no-confirm-project跳过或-i交互式确认--region单区域位置如us-east1、us-central1。校验逻辑见 validate_deployment_region多区域或 zone 会被拒绝-d / --deployment-target覆盖 manifest 中的目标也是无 manifest 部署的前提--service-name覆盖服务名Cloud Run 服务名或 Agent Runtime 显示名默认取项目名GKE 不支持--update-env-vars KEYVALUE逗号分隔的环境变量优先级高于.env--secrets ENVSECRET[:VERSION]从 Secret Manager 挂载密钥版本缺省为latest仅 Agent Runtime 与 Cloud Run 支持--service-account服务账号邮箱--dry-run / -n只打印将要执行的命令而不执行各目标打印内容不同见上文-i / --interactive为底层工具gcloud 等启用交互提示各目标的默认机器规格所有可调大小的参数都共享 _utils.py 中的默认常量生成的 Terraformservice.tf会手工同步这些值参数默认值设计意图--cpu1--memory4Gi配合默认并发度保证 RAG/大上下文 Agent 不超限--min-instances0默认缩容到零agents-cli deploy是迭代路径闲置的开发/演示实例会浪费区域配额--max-instances10--concurrency8保守值worker 是 I/O 密集型的但峰值内存随并发增长轻量 Agent 压测后可自行调高注意生产部署建议走 Terraform 路径其service.tf将min_instances固定为 1 以避免冷启动或显式传--min-instances。部署目标配置的来源agents-cli-manifest.yamldeployment_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.mdProjectConfig 读取逻辑 会优先读取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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考