google-agents-cli-deploy

部署指南

要求：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 — 基于容器的部署、统一的 FastAPI 应用、/api 透传、Terraform 资源、部署元数据、CI/CD 差异
• gke.md — GKE Autopilot 集群、Kubernetes 清单、Workload Identity、会话类型、网络
• terraform-patterns.md — 自定义基础设施、IAM、状态管理、导入资源
• batch-inference.md — BigQuery Remote Function 触发器；如需在 ADK 上使用 Pub/Sub / Eventarc，请参阅 /google-agents-cli-adk-code
• cicd-pipeline.md — 完整的 CI/CD 流水线设置、infra cicd 标志、运行器对比、WIF 身份验证、流水线阶段
• testing-deployed-agents.md — 各部署目标的测试说明、curl 示例、负载测试
• cmek.md — Gemini 平台上 Agent Runtime 的客户管理加密密钥：密钥授权、用于开发的 deploy --key、用于预发布/生产环境的 Terraform 修改

**可观测性：**如需了解 Cloud Trace、提示词-响应日志记录、BigQuery Analytics 和第三方集成，请参阅 /google-agents-cli-observability 技能。

---

部署目标决策矩阵

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

条件	Agent Runtime	Cloud Run	GKE
扩缩容	托管式自动扩缩容（可配置最小值/最大值、并发数）	完全可配置（最小值/最大值实例数、并发数、CPU 分配）	完整的 Kubernetes 扩缩容（HPA、VPA、节点自动预配）
网络	支持 VPC-SC 和 PSC-I（通过网络附件连接私有 VPC）	完整的 VPC 支持、直接 VPC 出口、IAP、入口规则	完整的 Kubernetes 网络
会话状态	Gemini 平台中的会话（ADK 会自动接入 VertexAiSessionService）	内存（开发环境）、Cloud SQL 或托管式会话后端	内存（开发环境）、Cloud SQL 或托管式会话后端
批处理/事件处理	可通过 Agent Runtime /api 透传访问触发端点	原生触发端点（Pub/Sub、Eventarc）；ADK：参见 /google-agents-cli-adk-code	自定义（Kubernetes Jobs、Pub/Sub）
成本模式	vCPU 小时 + 内存小时（空闲时不计费）	按实例秒计费 + 最小实例成本	节点池成本（持续运行或自动预配）
设置复杂度	较低（托管式，专为 Agent 构建）	中等（Dockerfile、Terraform、网络）	较高（需要 Kubernetes 专业知识）
最适合	托管式基础设施、尽量减少运维	自定义基础设施、完全掌控网络	完全掌控 Kubernetes

询问用户哪种部署目标最符合他们的需求。三种方案都适用于生产环境，只是各有取舍。

这三种目标均基于容器，因此可以使用任何语言。

产品名称映射： 用户可能会说“Agent Engine”、“Vertex AI Agent Engine”或“Agent Runtime”；它们都指 Agent Runtime。使用 --deployment-target agent_runtime。

环境式 / 定时 / 事件驱动 Agent（ADK 项目）： ADK 的 trigger_sources 会在同一个 FastAPI 应用中为所有目标注册 /apps/{app}/trigger/* 端点。在 Cloud Run / GKE 上，这些是公共 HTTP 路由，可供 Pub/Sub 推送订阅或 Eventarc 触发器调用；在 Agent Runtime 上，可通过其 /api 透传访问同一组路由（例如 .../reasoningEngines/v1/{resource}/api/apps/{app}/trigger/pubsub）。对于未经身份验证的触发源，Cloud Run 仍是最简单的目标。有关 trigger_sources 模式，请参见 /google-agents-cli-adk-code（references/adk-python.md，“12. Event-Driven / Ambient Agents”部分）。

OAuth / 用户许可 Agent： 对于需要 OAuth 2.0 用户许可的 Agent（例如访问 Google Drive、Calendar 或其他用户范围的 API），请使用已在 Gemini 中注册的 Agent Runtime。Cloud Run 目前不支持托管式 OAuth 流程。ADK 示例请在 /google-agents-cli-adk-code 的主题索引中查找 OAuth 用户许可 → references/samples.md。

实时和语音 Agent： 在 Cloud Run 上传入 --timeout 3600，让会话时长超过默认的 300s；在 Cloud Run 或 Agent Runtime 上传入 --min-instances 1，避免空闲后首位调用者遇到冷启动。GKE 会在 Terraform 中配置 Pod 规格。URL 格式和会话上限：/google-agents-cli-adk-code（references/adk-python-live.md）。

---

部署到开发环境

部署工作流

任务跟踪： 部署包含多个连续步骤（基础设施设置、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 deploy 可以独立运行。例外情况：如果用户需要由 Terraform 管理可观测性（提示词-响应日志记录、BigQuery 分析），请先运行 agents-cli infra single-project --apply，参见 /google-agents-cli-observability。

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

agents-cli infra single-project --apply 会在 deployment/terraform/single-project/ 中运行 terraform apply。使用此命令可在不配置 CI/CD 的情况下预配单项目 GCP 基础设施（服务账号、IAM 绑定、遥测资源、Artifact Registry）。只有在使用 Terraform 管理可观测性时，才需要在部署前运行此命令；基本的 Agent Runtime 和 Cloud Run 部署不需要，而 GKE 部署会处理自己的目标 Terraform。

# Optional — provision infrastructure in a single GCP project
agents-cli infra single-project --apply

注意： agents-cli deploy 不会自动使用 Terraform 创建的 app_sa。请显式传入服务账号：agents-cli deploy --service-account SA_EMAIL。

部署标志参考

标志	描述	目标
--project	GCP 项目 ID	全部
--region	GCP 区域	全部
--service-account	已部署 Agent 的服务账号电子邮件地址	全部
--service-name	覆盖已部署服务的名称（Cloud Run 服务或 Agent Runtime 显示名称）；默认为项目名称。若覆盖此名称，请考虑更新 Terraform 和 CI（如果存在）——它们会根据项目名称命名资源。GKE 不支持此选项，因为其名称完全由 Terraform 管理。	Agent Runtime、Cloud Run
--secrets / --update-secrets	以逗号分隔的 ENV=SECRET 或 ENV=SECRET:VERSION 键值对。Cloud Run 会将其添加到服务现有的密钥中；Agent Runtime 会用你传入的密钥替换 Agent 现有的密钥。	Agent Runtime、Cloud Run
--env-vars / --update-env-vars	以逗号分隔的 KEY=VALUE 环境变量	全部
--agent-identity	启用 Agent Identity	Agent Runtime
--no-agent-identity	禁用 Agent Identity。若既不传入 --agent-identity 也不传入 --no-agent-identity，则创建新 Agent 时默认不使用 Agent Identity；后续重新部署时则保留当前身份类型。	Agent Runtime
--network-attachment	用于 PSC 接口的网络连接资源名称（启用 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
--agent-gateway-egress	将 Agent 绑定到用于管理出站流量的 Agent Gateway。需提供 governedAccessPath=AGENT_TO_ANYWHERE 的网关完整资源名称。空值表示解除绑定；省略则保持不变。参见 Agent Gateway	Agent Runtime
--agent-gateway-ingress	将 Agent 绑定到用于管理入站流量的 Agent Gateway。需提供 governedAccessPath=CLIENT_TO_AGENT 的网关完整资源名称。空值表示解除绑定；省略则保持不变	Agent Runtime
--key	用于客户管理加密（CMEK）的 Cloud KMS 密钥，需使用完整的 projects/PROJECT/locations/REGION/keyRings/RING/cryptoKeys/KEY 名称。仅在创建时设置；对于开发部署（暂存/生产环境在 Terraform 中设置密钥）。参见客户管理加密（CMEK）	Agent Runtime
--memory	内存限制（默认值：4Gi）	Agent Runtime、Cloud Run
--cpu	CPU 限制（默认值：1）	Agent Runtime、Cloud Run
--min-instances	最小实例数（默认值：0，即缩减至零；生成的 Terraform 使用 1）	Agent Runtime、Cloud Run
--max-instances	最大实例数（默认值：10）	Agent Runtime、Cloud Run
--concurrency	每个容器的并发请求数（默认值：8；参见部署容量规划）	Agent Runtime、Cloud Run
--timeout	请求超时时间（秒），最长为 3600（Cloud Run 默认值：300）。创建和更新时均会应用；未设置则保留服务当前值	Cloud Run
--port	容器端口	Cloud Run、Agent Runtime
--build-args	以逗号分隔的 KEY=VALUE Docker 构建参数	Agent Runtime
--labels / --update-labels	以逗号分隔的 KEY=VALUE 资源标签，用于添加或更新。采用增量方式：添加或更新指定的标签；未指定的标签会保留。	Agent Runtime、Cloud Run
--remove-labels	以逗号分隔的要移除的标签 KEY。不存在的键会被忽略。可与 --labels 一起使用，但同一个键不能同时出现在两者中。不能与 --clear-labels 一起使用。	Agent Runtime、Cloud Run
--clear-labels	移除所有资源标签（Cloud Run 会保留其保留标签 created-by）。与 --labels 一起使用可替换标签集；先执行清除操作。不能与 --remove-labels 一起使用。	Agent Runtime、Cloud Run
--framework	已部署容器所实现的框架（默认使用 agents-cli-manifest.yaml 中的 framework:，模板会设置该项；若不存在，则使用 google-adk）。在部署中设置 agent_framework，该值决定 Google Cloud 控制台 Playground 的选择，以及部署声明的运行时契约。可接受的值由 API 决定（参考）	Agent Runtime
--iap	启用 Identity-Aware Proxy	Cloud Run
--image	容器映像 URI（跳过源代码构建；Agent Runtime 不支持）	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 查看完整的标志参考。

Cloud Run 高级部署： 如果需要使用 agents-cli 标志未提供的功能，请使用 --dry-run（或 -n）打印完整的 gcloud 命令，复制后按需添加其他参数。

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

---

部署规格

默认值（Agent Runtime 和 Cloud Run 相同）：--cpu 1、--memory 4Gi、--concurrency 8、--min-instances 0、--max-instances 10。生成的 service.tf 与之匹配，但会将 min_instances = 1 固定为 1，以避免生产部署出现冷启动。建议值是针对 Python Agent 调整的，因此应将其视为起点，并通过负载测试进行调整（见下文）。

agents-cli deploy 默认会缩容至零，避免空闲的开发和演示 Agent 占用容量。需要保持实例预热时，请传入 --min-instances 1（或通过 Terraform 部署）。

这些参数相互关联，应一起调整：

• 单进程——扩展实例数，而非规格。 容器运行单个服务进程并发处理多个请求，因此吞吐量取决于 --concurrency 和水平扩展（--max-instances），而非额外的工作进程。只有在性能分析显示 CPU 确实饱和，而非时间花在等待模型上时，才提高 --cpu。
• 内存限制并发数。 每个并发请求在等待模型时都会将其完整工作集（上下文窗口、历史记录、RAG 分块、响应缓冲区）保留在内存中，因此峰值约为基础内存 + concurrency × 每个请求的内存。内存而非 CPU 是首要限制，因此不提高 --memory 就提高 --concurrency，是导致 OOM 的主要原因。
• 并发数默认值较为保守。 工作进程在等待模型时可以处理许多并发请求，但每个请求的内存占用因 Agent 而异，因此 8 能保护内存占用较高的 Agent（RAG/多模态）。轻量级 Agent 可在负载测试后提高到 16–32+。参见未充分利用的异步工作进程。

# 4x throughput: scale every param, not just one
agents-cli deploy --cpu 4 --concurrency 16 --memory 16Gi --max-instances 20

使用脚手架生成的负载测试进行调优（Python 项目位于 tests/load_test/，Go 项目位于 e2e/load_test/；可在本地或 CI/CD 预发布流水线中运行）：施加负载，观察最大延迟以及内存/OOM 重启情况，然后进行调整——最大延迟较高 → 提高并发数（+ 工作进程/CPU）；发生 OOM → 增加内存或降低并发数。

在 GKE 上不支持这些规格标志——请通过 deployment/terraform/ 下的 Terraform 清单和 HorizontalPodAutoscaler 调整规格。

---

生产部署 — CI/CD 流水线

完整的 CI/CD 流水线设置指南（包括前置条件、infra cicd 标志、运行器比较、WIF 身份验证、流水线阶段和生产审批），请参见 references/cicd-pipeline.md。

---

Cloud Run 专项说明

有关详细的基础设施配置（扩缩容默认值、Dockerfile、FastAPI 端点、会话类型、网络），请参见 references/cloud-run.md。ADK： 如需查看 ADK 关于在 Cloud Run 上部署的文档，请获取 https://adk.dev/deploy/cloud-run/index.md。

ADK 项目。 如需在 Cloud Run 上部署事件驱动型 / 环境式 Agent，请参见 ambient-expense-agent 示例，以及 /google-agents-cli-adk-code（references/adk-python.md 中的“12. 事件驱动型 / 环境式 Agent”章节），了解 trigger_sources 模式。

---

Agent Runtime 具体说明

Agent Runtime 是一项托管的 Gemini 平台服务，可将 Agent 作为容器部署。它采用基于容器的部署方式：agents-cli deploy 会打包你的项目，Agent Runtime 则从项目的 Dockerfile（必需）构建镜像——该镜像也用于 Cloud Run 和 GKE。

Agent Runtime 没有 gcloud CLI。 使用 agents-cli deploy 进行部署。使用 Python agentplatform.Client SDK 进行查询。

部署可能需要 5-10 分钟。使用 --no-wait 启动部署并立即返回，之后再使用 --status 查看状态：

# Start deployment without blocking
agents-cli deploy --no-wait

# Check on progress later
agents-cli deploy --status

当 --status 检测到操作已完成时，它会写入 deployment_metadata.json，并打印与正常部署相同的成功输出。

有关详细的基础设施配置（容器部署流程、统一的 FastAPI 应用和 /api 直通、Terraform 资源、部署元数据、会话/工件服务、CI/CD 差异），请参阅 references/agent-runtime.md。**ADK：**有关 Agent Runtime 部署的 ADK 文档，请获取 https://adk.dev/deploy/agent-runtime/index.md。

---

GKE 具体说明

有关详细的基础设施配置（Kubernetes 清单、Terraform 资源、Workload Identity、会话类型、网络），请参阅 references/gke.md。**ADK：**有关 GKE 部署的 ADK 文档，请获取 https://adk.dev/deploy/gke/index.md。

---

服务账号架构

生成的项目使用两个服务账号：

• app_sa（每个环境各一个）——已部署 Agent 的运行时身份。角色定义在 deployment/terraform/iam.tf 中。
• cicd_runner_sa（CI/CD 项目）——CI/CD 流水线身份（GitHub Actions / Cloud Build）。位于 CI/CD 项目中（默认为 prod 项目），需要在 staging 和 prod 项目中都拥有权限。

请查看 deployment/terraform/iam.tf，了解确切的角色绑定。跨项目权限（Cloud Run 服务代理、Artifact Registry 访问权限）也在此处配置。

常见的 403 错误：

• “Cloud Run 权限被拒绝” → cicd_runner_sa 缺少目标项目中的部署角色
• “无法以服务账号身份操作” → app_sa 缺少 iam.serviceAccountUser 绑定
• “Secret 访问被拒绝” → app_sa 缺少 secretmanager.secretAccessor
• “Cloud SQL 连接失败 / 未授权” → 运行时服务账号缺少 roles/cloudsql.client
• “Artifact Registry 读取被拒绝” → Cloud Run 服务代理缺少 CI/CD 项目中的读取权限

---

CI/CD 设置所需权限

• 在 CI/CD 项目中，将 roles/secretmanager.admin 授予 Cloud Build 服务账号（service-<PROJECT_NUMBER>@gcp-sa-cloudbuild.iam.gserviceaccount.com）。这允许 Cloud Build 访问存储在 Secret Manager 中的 GitHub token。

---

所需 API

必须在项目中启用以下 Google Cloud API，相关技能和部署才能正常工作：

• cloudbuild.googleapis.com — 构建容器镜像和运行 CI/CD 流水线所必需。
• secretmanager.googleapis.com — 管理机密和 API 密钥所必需。
• run.googleapis.com — 部署到 Cloud Run 所必需。

运行部署或 CI/CD 设置命令前，请确保已启用这些 API：

gcloud services enable cloudbuild.googleapis.com secretmanager.googleapis.com run.googleapis.com --project=YOUR_PROJECT_ID

---

Secret Manager（用于 API 凭据）

不要将敏感密钥作为环境变量传递，而应使用 GCP Secret Manager。

# Create a secret
echo -n "YOUR_API_KEY" | gcloud secrets create MY_SECRET_NAME --data-file=-

# Update an existing secret
echo -n "NEW_API_KEY" | gcloud secrets versions add MY_SECRET_NAME --data-file=-

**授予访问权限：**对于 Cloud Run，将 secretmanager.secretAccessor 授予 app_sa。对于 Agent Runtime，将其授予平台管理的 SA（service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com）。对于 GKE，将 secretmanager.secretAccessor 授予 app_sa。可通过 Kubernetes Secrets 或结合 Workload Identity 直接调用 Secret Manager API 来访问机密。

在部署时传递机密（Agent Runtime、Cloud Run）：

agents-cli deploy --secrets "API_KEY=my-api-key,DB_PASS=db-password:2"

格式：ENV_VAR=SECRET_ID 或 ENV_VAR=SECRET_ID:VERSION（默认使用 latest）。

---

Cloud SQL 权限（手动部署）

在手动部署中使用 Cloud SQL 和 Cloud Run 时（例如，在非 Terraform 配置中添加 --add-cloudsql-instances），必须手动为运行时服务账号授予 Cloud SQL Client 角色。

如果不这样做，部署可能会成功，但运行时会因 cloudsql.instances.get 授权错误而失败。

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:YOUR_RUNTIME_SA_EMAIL" \
  --role="roles/cloudsql.client"

注意： 在由 Terraform 完全管理的配置中（infra cicd / infra single-project），此角色会自动配置和管理。

---

可观测性

有关可观测性配置（Cloud Trace、提示词-响应日志记录、BigQuery Analytics、第三方集成），请参阅 agents-cli-observability 技能。

---

测试已部署的 Agent

测试已部署 Agent 的最快方式是运行 agents-cli run --url <service-url> --mode a2a "your prompt"——它会自动处理身份验证、会话和流式传输（支持 Agent Runtime 和 Cloud Run）。ADK： --mode adk 会调用 ADK 流式 API。

有关高级测试（自定义标头、会话复用、脚本编写、负载测试），请参阅 references/testing-deployed-agents.md。

---

使用 UI 部署（IAP）

IAP（Identity-Aware Proxy）可以保护 Cloud Run 服务，确保只有获得授权的 Google 账号才能访问。部署时添加 --iap 标志即可启用（仅适用于 Cloud Run）：agents-cli deploy --iap。

对于带有自定义前端的 Agent Runtime，请使用解耦部署——将前端单独部署到 Cloud Run 或 Cloud Storage，并连接到 Agent Runtime 后端 API。

有关 Cloud Run 的 IAP 的更多信息，请参阅 Cloud Console IAP 设置。

---

回滚与恢复

主要回滚方式是基于 git 的回滚：修复问题、提交更改并推送到 main。CI/CD 流水线会自动构建新版本，并通过预发布环境 → 生产环境完成部署。

如需立即回滚 Cloud Run，且不创建新提交，请使用修订版本流量切换：

gcloud run revisions list --service=SERVICE_NAME --region=REGION
gcloud run services update-traffic SERVICE_NAME \
  --to-revisions=REVISION_NAME=100 --region=REGION

Agent Runtime 不支持基于修订版本的回滚——请修复问题并通过 agents-cli deploy 重新部署。

如需回滚 GKE，请使用 kubectl rollout undo：

kubectl rollout undo deployment/DEPLOYMENT_NAME -n NAMESPACE
kubectl rollout status deployment/DEPLOYMENT_NAME -n NAMESPACE

---

自定义基础设施（Terraform）

重要： 如果 Agent 需要自定义基础设施（Cloud SQL、Pub/Sub、Eventarc、BigQuery 等），必须在 Terraform 中定义，切勿通过 gcloud 命令手动创建资源。例外情况：可以使用 gcloud 或控制台进行快速试验，但生产基础设施必须使用 Terraform 管理。

有关自定义基础设施模式，请参阅 references/terraform-patterns.md，了解以下内容：

• 自定义 Terraform 文件的存放位置（单项目或 CI/CD）
• 资源示例（Pub/Sub、BigQuery、Eventarc 触发器）
• 自定义资源的 IAM 绑定
• Terraform 状态管理（远程或本地、导入资源）
• 常见基础设施模式

---

故障排除

问题	解决方案
Terraform 状态已锁定	在 deployment/terraform/ 中运行 terraform force-unlock -force LOCK_ID
GitHub Actions 身份验证失败	在 CI/CD terraform 目录中重新运行 terraform apply；验证 WIF 池/提供方
Cloud Build 授权待处理	改用 github_actions runner
资源已存在	使用 terraform import（参见 references/terraform-patterns.md）
Agent Runtime 部署超时/卡住	部署需要 5-10 分钟；检查引擎是否已创建（参见 Agent Runtime 特殊说明）
密钥不可用	确认已向 app_sa 授予 secretAccessor（而非默认 compute SA）
Cloud SQL 连接失败/403	使用手动部署时，向运行时服务账号授予 roles/cloudsql.client
部署时出现 403	检查 deployment/terraform/iam.tf — cicd_runner_sa 在目标项目中需要部署和 SA 模拟角色
测试 Cloud Run 时出现 403	默认设置为 --no-allow-unauthenticated；请加入 Authorization: Bearer $(gcloud auth print-identity-token) 标头
冷启动太慢	在 Cloud Run Terraform 配置中设置 min_instance_count > 0
Cloud Run 出现 503 错误	检查资源限制（内存/CPU），增加 max_instance_count，或检查容器崩溃日志
授予 IAM 角色后立即出现 403	IAM 传播并非即时完成 — 请等待几分钟后再重试。不要反复授予同一个角色
资源似乎缺失，但 Terraform 已创建	运行 terraform state list，检查 Terraform 实际管理的内容。通过 null_resource + local-exec 创建的资源（例如，BQ 链接数据集）不会出现在 gcloud CLI 输出中
部署失败或 Agent 无响应	检查 Cloud Logging：对于 Cloud Run，运行 gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE" --project=PROJECT --limit=50 --format="table(timestamp,severity,textPayload)"；对于 Agent Runtime，运行 gcloud logging read "resource.type=aiplatform.googleapis.com/ReasoningEngine" --project=PROJECT --limit=50
Agent 部署后返回错误	在 Console 中打开 Cloud Logging → 按服务名称（Cloud Run）或 reasoning engine 资源（Agent Runtime）筛选 → 在最近的日志条目中查找堆栈跟踪或权限错误

---

平台注册

如需了解如何将已部署的 Agent 注册到 Gemini，请参阅 /google-agents-cli-publish。

---

Agent Gateway

Note: 没有用于创建或管理 Agent Gateway 或 Semantic Governance 政策的 agents-cli 命令——请单独设置（通过 Terraform 或 Cloud Console）。 agents-cli deploy 是唯一支持网关的命令，其支持方式是透传：它会在 Agent Runtime 创建/更新调用中，将 Agent 绑定到现有网关。

Agent Gateway 是所有 Agent 交互（用户↔Agent、Agent↔工具、Agent↔Agent）的网络与安全入口/出口点——它集中管理访问控制和受管控的连接（入站/出站）。它不是部署目标。

如需设置网关，请参阅设置 Agent Gateway和通过 Agent Gateway 路由 Agent Runtime 流量。你也可以通过 google_network_services_agent_gateway 使用 Terraform 管理网关（目前属于 google-beta 提供程序）。

网关创建后，agents-cli deploy 会通过 --agent-gateway-egress 和/或 --agent-gateway-ingress 将 Agent 绑定到该网关；每个参数都需要完整的资源名称（projects/PROJECT/locations/REGION/agentGateways/GATEWAY）。目前仅支持 Agent Runtime 部署，并且 Agent 必须具有 Agent Identity。

出站网关会对 Agent 的出站通信进行 TLS 解密和检查，因此镜像必须信任网关的根 CA。此设置需在构建脚手架时选择启用。若要创建新项目，请向 agents-cli create 传入 --agent-gateway 标志：

agents-cli create my-agent --agent adk -d agent_runtime --agent-gateway

或者，也可以向 agents-cli scaffold enhance 传入相同的标志，以升级现有项目：

agents-cli scaffold enhance . --agent-gateway

这两种方式都会写入一个 Dockerfile，该文件会使用平台注入的 AGENT_GATEWAY_ROOT_CERTIFICATES 构建参数，并在 create_params 下记录 agent_gateway: true，以便 scaffold upgrade 保留此设置。若使用 --agent-gateway-egress 部署，但 Dockerfile 中缺少该构建参数，部署会失败并提示使用上述命令；--no-agent-gateway 可移除此设置。

背景信息：Agent Gateway 概览。

客户管理的加密（CMEK）

Agent Runtime Agent 可以使用你的 Cloud KMS 密钥加密。密钥在创建时确定，因此应在创建 Agent 的位置设置：开发部署使用 deploy --key；暂存/生产环境（infra cicd）和 infra single-project 使用 Terraform 文件。--key 无法为 Terraform 创建的 Agent 添加密钥。所需的密钥授权和 Terraform 修改：references/cmek.md。

Semantic Governance

Semantic Governance Policies（SGP） 会添加自然语言安全/合规层，确保 Agent 的工具调用符合用户意图和组织约束。

• 概览：https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/policies/semantic-governance-overview
• 配置：https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/policies/configure-semantic-governance

---

相关技能

• /google-agents-cli-workflow — 开发工作流、编码指南和操作规则
• /google-agents-cli-adk-code — 编写 Agent 代码时的 ADK API 快速参考
• /google-agents-cli-eval — 评估方法、数据集架构和评估修复循环
• /google-agents-cli-scaffold — 使用 agents-cli scaffold create / scaffold enhance 创建和增强项目
• /google-agents-cli-observability — Cloud Trace、日志记录、BigQuery Analytics 和第三方集成
• /google-agents-cli-publish — Gemini 注册