google-agents-cli-publish

Gemini 注册

要求： 已部署的 Agent。对于 Gemini 平台上的 Agent Runtime，deployment_metadata.json（由 agents-cli deploy 创建）可启用自动检测。对于 Cloud Run 或 GKE，请直接提供 Agent 卡片 URL 和标志。

前提条件

1. Agent 必须已部署 — Agent 必须正在运行且可访问
2. Gemini 应用必须已存在 — 注册前请先在 Google Cloud 控制台中创建应用
3. deployment_metadata.json（仅限 Agent Runtime）— 由 agents-cli deploy 自动创建；包含 Agent Runtime ID、部署目标、A2A 标志和 Agent 目录
4. 基于文本的 Agent — Gemini 应用不支持 Live/语音（bidi）Agent，因为它没有 /run_live 传输方式。请改为注册基于文本的 Agent。

Cloud Run 上 A2A 所需的权限

• 将 roles/run.servicesInvoker 授予 Discovery Engine 服务账号（service-<PROJECT_NUMBER>@gcp-sa-discoveryengine.iam.gserviceaccount.com），并作用于 Cloud Run 服务。

---

注册模式

A2A 注册

每个脚手架生成的 Agent 都提供 Agent-to-Agent 协议服务。A2A 是 Cloud Run 和 GKE 上的默认且唯一的注册类型（没有可原生调用的推理引擎）。也可以通过 --registration-type a2a 在 Agent Runtime 上使用。对于 ADK Agent，CLI 会对此发出警告，因为 Gemini 应用可以通过 :streamQuery 原生调用 Agent Runtime — 此时建议使用 ADK 注册。对于基于其他框架构建的 Agent，没有可原生调用的 ADK 应用，因此 A2A 是所有部署目标上的合适模式，并且出现该警告是预期行为。传入 Agent 卡片 URL，命令会获取卡片并进行注册；显示名称和描述默认取自卡片的 name/description。

# A2A on Cloud Run / GKE. The card path depends on the project's language:
#   Python -> /a2a/{app_name}/.well-known/agent-card.json
#   Go     -> /.well-known/agent-card.json
agents-cli publish gemini \
  --agent-card-url https://my-service-abc123.us-east1.run.app/a2a/app/.well-known/agent-card.json \
  --gemini-app-id projects/123456/locations/global/collections/default_collection/engines/my-app

传入 --display-name / --description 可覆盖卡片中的默认值。在 Agent Runtime 上，如果省略 --agent-card-url，系统会根据 deployment_metadata.json 自动构建卡片 URL。

ADK 注册（Agent Runtime 上的默认方式）

仅限 ADK 项目。 Agent 必须作为 ADK 应用部署到 Agent Runtime，因为 注册会通过 :streamQuery 调用它。基于其他框架的 Agent 通过 A2A 注册，因此请将其部署到 Cloud Run 或 GKE，并从那里发布。

这是 Agent Runtime 上 ADK Agent 的默认且推荐注册方式：Gemini 应用通过其推理引擎资源上的 :streamQuery 原生调用 Agent，并进行端到端身份验证。在底层，:streamQuery 会分发到 AdkApp 的 streaming_agent_run_with_events 方法 — 调试 ADK 调用时，请在运行时的 reasoning_engine_stderr 日志中搜索该方法名称，以追踪故障。如果 Agent 需要 OAuth 授权（--authorization-id），也应使用此方式。Agent 通过其推理引擎资源名称直接注册；无需 Agent 卡片 URL。

agents-cli publish gemini \
  --registration-type adk \
  --agent-runtime-id projects/123456/locations/us-east1/reasoningEngines/789 \
  --gemini-app-id projects/123456/locations/global/collections/default_collection/engines/my-app \
  --display-name "My Agent" \
  --description "Handles customer queries" \
  --tool-description "Answers questions about products"

---

编程模式（CI/CD）

该命令默认以非交互方式运行 — 通过标志或环境变量传入所有必需值。这样可安全地用于 CI/CD 流水线。

通过标志

agents-cli publish gemini \
  --agent-runtime-id "$AGENT_RUNTIME_ID" \
  --gemini-app-id "$GEMINI_APP_ID" \
  --display-name "Production Agent" \
  --registration-type adk

通过环境变量

大多数标志都有对应的环境变量（--metadata-file、--interactive 和 --list 除外）：

export AGENT_RUNTIME_ID="projects/123456/locations/us-east1/reasoningEngines/789"
export GEMINI_APP_ID="projects/123456/locations/global/collections/default_collection/engines/my-app"
export GEMINI_DISPLAY_NAME="Production Agent"
export GEMINI_DESCRIPTION="Handles customer queries"

agents-cli publish gemini

---

交互模式（--interactive）

传入 --interactive（或 -i），即可通过交互式提示填写任何缺失的值。该命令会列出可用的 Gemini 应用，提供从元数据自动检测 Agent Runtime ID 的选项，并提示输入显示名称和描述。

agents-cli publish gemini --interactive

---

完整标志参考

标志	环境变量	描述
--agent-runtime-id	AGENT_RUNTIME_ID	Agent Runtime 资源名称（从 deployment_metadata.json 自动检测）
--gemini-app-id	GEMINI_APP_ID	Gemini 应用的完整资源名称
--display-name	GEMINI_DISPLAY_NAME	在 Gemini 中显示的名称
--description	GEMINI_DESCRIPTION	Agent 描述
--tool-description	GEMINI_TOOL_DESCRIPTION	工具描述（仅限 ADK 模式，默认使用描述）
--registration-type	REGISTRATION_TYPE	adk 或 a2a（对于 Agent Runtime 上的 ADK Agent，默认为 adk；其他所有情况均默认为 a2a，包括使用任何非 ADK 框架的情况）
--agent-card-url	AGENT_CARD_URL	用于 A2A 注册的 Agent 卡片 URL
--deployment-target	DEPLOYMENT_TARGET	agent_runtime、cloud_run 或 gke（设置默认注册类型——Agent Runtime 上的 ADK、Cloud Run / GKE 上的 A2A——以及 A2A 身份验证方法）
--project-id	GOOGLE_CLOUD_PROJECT	用于结算的 GCP 项目 ID
--project-number	PROJECT_NUMBER	GCP 项目编号（用于查找 Gemini 应用）
--authorization-id	GEMINI_AUTHORIZATION_ID	OAuth 授权资源名称
--metadata-file	—	部署元数据路径（默认值：deployment_metadata.json）
--interactive / -i	—	启用交互式提示
--list	—	列出当前项目中的 Gemini 应用并退出

旧名称仍可作为隐藏别名使用：publish gemini-enterprise、--gemini-enterprise-app-id，以及 ID / GEMINI_ENTERPRISE_APP_ID 环境变量。早期版本生成的项目会从 make publish-gemini-enterprise 调用 publish gemini-enterprise；较新的 Go 和 Java 项目会保留该目标，并添加 make publish-gemini 作为别名。

---

从元数据自动检测

存在 deployment_metadata.json 时，该命令会自动：

• 读取 Agent Runtime ID（remote_agent_runtime_id）
• 确定注册类型：在 Agent Runtime 上默认为 ADK（原生 :streamQuery），在 Cloud Run / GKE 上默认为 A2A（这些环境没有推理引擎）。使用其他框架搭建的项目不会提供 ADK 应用，因此在所有部署目标上都默认为 A2A。可通过 --registration-type 覆盖。
• 确定用于身份验证的部署目标

这意味着，对于最简单的情况（在 Agent Runtime 上注册为 ADK 的 ADK Agent），只需提供 Gemini 应用 ID：

agents-cli publish gemini \
  --gemini-app-id projects/123456/locations/global/collections/default_collection/engines/my-app

---

Agent Registry（Agent 和 MCP 服务）

Agent Registry（预览版）是 Google Cloud 面向整个服务群的 Agent 和 MCP 服务目录，与 Gemini 应用相互独立。 部署到托管运行时（Gemini 平台中的 Agent Runtime）的 Agent 会自动注册——无需在 agents-cli deploy 后执行额外步骤。 使用 gcloud 管理（需要 roles/agentregistry.editor）：

# List / inspect agents
gcloud agent-registry agents list --project PROJECT --location LOCATION
gcloud agent-registry agents describe AGENT_NAME

# Update endpoint/metadata — edit the Service resource, not the Agent
gcloud agent-registry services update AGENT_NAME \
  --display-name "..." --description "..." \
  --interfaces "url=ENDPOINT_URL,protocolBinding=http-json"

# Register an external MCP server: not auto-introspected, so upload a
# toolspec.json (its tools/list response, max 10 KB). No us/eu multi-region.
gcloud agent-registry services create SERVER_NAME --location=LOCATION \
  --mcp-server-spec-type=tool-spec --mcp-server-spec-content=toolspec.json \
  --interfaces="url=SERVER_URL,protocolBinding=jsonrpc"  # or http-json, grpc

# Remove: delete the underlying runtime agent (auto-registered) OR, for
# manually registered agents/servers, delete the Service resource
gcloud agent-registry services delete NAME

Terraform：使用带有 mcp_server_spec 块的 google_agent_registry_service。

文档：https://docs.cloud.google.com/agent-registry/manage-agents · https://docs.cloud.google.com/agent-registry/register-mcp-servers

---

故障排除

问题	解决方案
注册后显示“Session not found”	使用 google-cloud-aiplatform <= 1.128.0 的 Python 项目会遇到已知的 SDK 错误 — 请升级，然后重新部署并重新注册
--registration-type is required	在不存在 deployment_metadata.json 时，非交互模式需要 --registration-type
“Gemini app ID is required”	提供 --gemini-app-id 或设置 GEMINI_APP_ID 环境变量
重新发布同一 Agent	注册操作具有幂等性 — 重新运行会就地更新现有注册，而不是创建重复项
注册时出现 HTTP 403	检查你的账号是否对托管 Gemini 应用的项目拥有 Discovery Engine Editor 权限
调试 Agent Runtime 上的 ADK 调用失败	Gemini 应用通过 AdkApp 的 streaming_agent_run_with_events 方法调用 Agent（原生 :streamQuery 契约）。在运行时的 reasoning_engine_stderr 日志中搜索 streaming_agent_run_with_events，以查找根本错误
“Could not fetch agent card”	确认 Agent 正在运行且 URL 正确；对于 Cloud Run，请确保已执行 gcloud auth login。Live/语音 Agent 不提供 A2A 卡片，因此无法发布 — Gemini 应用不支持 Live Agent

---

相关技能

• /google-agents-cli-deploy — 部署目标、CI/CD 流水线和生产工作流（也涵盖 Agent Gateway 管理的入口/出口流量和 Semantic Governance 感知）
• /google-agents-cli-workflow — 开发工作流、编码指南和操作规则
• /google-agents-cli-scaffold — 使用 agents-cli scaffold create / scaffold enhance 创建和增强项目