google-agents-cli-publish
热门当用户想要“发布智能体”、“发布我的ADK智能体”、“向Gemini Enterprise注册智能体”、“发布到Gemini Enterprise”，或需要关于agents-cli publish gemini-enterprise命令的指导时，应使用此技能。当用户想要“在Agent Registry中管理智能体”或“列出/更新/删除已注册的智能体”时，也应使用此技能。涵盖ADK与A2A注册模式、编程式和交互式用法、标志参考、从部署元数据自动检测、Agent Registry集群管理以及故障排除。属于Google ADK（Agent Development Kit）技能套件的一部分。请勿用于部署（请使用google-agents-cli-deploy）。
当用户想要“发布智能体”、“发布我的ADK智能体”、“向Gemini Enterprise注册智能体”、“发布到Gemini Enterprise”，或需要关于agents-cli publish gemini-enterprise命令的指导时，应使用此技能。当用户想要“在Agent Registry中管理智能体”或“列出/更新/删除已注册的智能体”时，也应使用此技能。涵盖ADK与A2A注册模式、编程式和交互式用法、标志参考、从部署元数据自动检测、Agent Registry集群管理以及故障排除。属于Google ADK（Agent Development Kit）技能套件的一部分。请勿用于部署（请使用google-agents-cli-deploy）。
Gemini Enterprise 注册
前提条件： 已部署的智能体。对于 Agent Runtime，
deployment_metadata.json（由agents-cli deploy创建）支持自动检测。对于 Cloud Run 或 GKE，请直接提供智能体卡片 URL 和标志。
先决条件
- 智能体必须已部署 — 智能体必须正在运行且可访问
- Gemini Enterprise 应用必须存在 — 在 Google Cloud 控制台 → Gemini Enterprise → 应用中创建一个，然后再注册
deployment_metadata.json（仅 Agent Runtime）— 由agents-cli deploy自动创建；包含智能体运行时 ID、部署目标和 A2A 标志
A2A 在 Cloud Run 上的必需权限
roles/run.servicesInvoker授予 Discovery Engine 服务账号（service-<PROJECT_NUMBER>@gcp-sa-discoveryengine.iam.gserviceaccount.com）在 Cloud Run 服务上。
注册模式
ADK 注册（默认）
适用于部署到 Agent Runtime 的标准 ADK 智能体。智能体通过其推理引擎资源名称直接注册。
agents-cli publish gemini-enterprise \
--agent-runtime-id projects/123456/locations/us-east1/reasoningEngines/789 \
--gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app \
--display-name "我的智能体" \
--description "处理客户查询" \
--tool-description "回答关于产品的问题"
A2A 注册
适用于使用智能体间协议的智能体。需要智能体卡片 URL — 该命令会获取卡片并注册。
# A2A 在 Cloud Run 上
agents-cli publish gemini-enterprise \
--registration-type a2a \
--agent-card-url https://my-service-abc123.us-east1.run.app/a2a/app/.well-known/agent-card.json \
--gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app \
--display-name "我的 A2A 智能体"
# A2A 在 Agent Runtime 上（卡片 URL 从元数据自动构建）
agents-cli publish gemini-enterprise \
--registration-type a2a \
--gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app
编程模式（CI/CD）
该命令默认是非交互式的 — 通过标志或环境变量传递所有必需的值。这使得它适用于 CI/CD 流水线。
通过标志
agents-cli publish gemini-enterprise \
--agent-runtime-id "$AGENT_RUNTIME_ID" \
--gemini-enterprise-app-id "$GEMINI_ENTERPRISE_APP_ID" \
--display-name "生产智能体" \
--registration-type adk
通过环境变量
大多数标志都有对应的环境变量替代（--metadata-file、--interactive 和 --list 除外）：
export AGENT_RUNTIME_ID="projects/123456/locations/us-east1/reasoningEngines/789"
export GEMINI_ENTERPRISE_APP_ID="projects/123456/locations/global/collections/default_collection/engines/my-app"
export GEMINI_DISPLAY_NAME="生产智能体"
export GEMINI_DESCRIPTION="处理客户查询"
agents-cli publish gemini-enterprise
交互模式（--interactive）
传递 --interactive（或 -i）以通过交互式提示引导您填写任何缺失的值。该命令会列出可用的 Gemini Enterprise 应用，提供从元数据自动检测智能体运行时 ID 的选项，并提示输入显示名称和描述。
agents-cli publish gemini-enterprise --interactive
完整标志参考
| 标志 | 环境变量 | 描述 |
|---|---|---|
--agent-runtime-id |
AGENT_RUNTIME_ID |
Agent Runtime 资源名称（从 deployment_metadata.json 自动检测） |
--gemini-enterprise-app-id |
ID 或 GEMINI_ENTERPRISE_APP_ID |
Gemini Enterprise 应用完整资源名称 |
--display-name |
GEMINI_DISPLAY_NAME |
在 Gemini Enterprise 中的显示名称 |
--description |
GEMINI_DESCRIPTION |
智能体描述 |
--tool-description |
GEMINI_TOOL_DESCRIPTION |
工具描述（仅 ADK 模式，默认为描述） |
--registration-type |
REGISTRATION_TYPE |
adk 或 a2a（如果未设置，则从元数据自动检测） |
--agent-card-url |
AGENT_CARD_URL |
A2A 注册的智能体卡片 URL |
--deployment-target |
DEPLOYMENT_TARGET |
agent_runtime、cloud_run 或 gke（影响 A2A 认证方法） |
--project-id |
GOOGLE_CLOUD_PROJECT |
GCP 项目 ID（用于计费） |
--project-number |
PROJECT_NUMBER |
GCP 项目编号（用于 Gemini Enterprise 查找） |
--authorization-id |
GEMINI_AUTHORIZATION_ID |
OAuth 授权资源名称 |
--metadata-file |
— | 部署元数据路径（默认：deployment_metadata.json） |
--interactive / -i |
— | 启用交互式提示 |
--list |
— | 列出当前项目中的 Gemini Enterprise 应用并退出 |
从元数据自动检测
当 deployment_metadata.json 存在时，该命令会自动：
- 读取智能体运行时 ID（
remote_agent_runtime_id） - 检测注册类型（
is_a2a标志） - 为 Agent Runtime 上的 A2A 智能体构建智能体卡片 URL
- 确定用于认证的部署目标
这意味着对于最简单的情况（Agent Runtime 上的 ADK 智能体），您只需提供 Gemini Enterprise 应用 ID：
agents-cli publish gemini-enterprise \
--gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app
SDK 兼容性
Agent Runtime 部署可能会遇到 google-cloud-aiplatform 版本 <= 1.128.0 的“Session not found”错误。在交互模式（--interactive）下，该命令会检查 uv.lock 中的 SDK 版本并提供升级选项。在编程模式下，请确保在注册前更新 SDK。
在 Agent Registry 中管理智能体
Agent Registry（预览版）是 Google Cloud 中智能体的集群级记录。
部署到托管运行时（Gemini Enterprise Agent Platform 上的 Agent Runtime）的智能体会自动注册 — 在 agents-cli deploy 之后无需额外步骤。
使用 gcloud 进行管理（需要 roles/agentregistry.editor）：
# 列出/过滤
gcloud alpha agent-registry agents list --project PROJECT --location LOCATION
gcloud alpha agent-registry agents list --filter="displayName:my-agent"
# 检查
gcloud alpha agent-registry agents describe AGENT_NAME
# 更新端点/元数据 — 编辑 Service 资源，而不是 Agent
gcloud alpha agent-registry services update AGENT_NAME \
--display-name "..." --description "..." \
--interfaces "url=ENDPOINT_URL,protocol=HTTP_JSON"
# 删除：删除底层运行时智能体（自动注册）或，对于手动注册的智能体，删除 Service 资源
gcloud alpha agent-registry services delete AGENT_NAME
文档：https://docs.cloud.google.com/agent-registry/manage-agents
故障排除
| 问题 | 解决方案 |
|---|---|
| 注册后出现“Session not found” | SDK 版本问题 — 升级 google-cloud-aiplatform（参见上面的 SDK 兼容性），重新部署，然后重新注册 |
--registration-type is required |
当没有 deployment_metadata.json 时，非交互模式需要 --registration-type |
| “Gemini Enterprise App ID is required” | 提供 --gemini-enterprise-app-id 或设置 ID / GEMINI_ENTERPRISE_APP_ID 环境变量 |
| 重新发布同一智能体 | 注册是幂等的 — 重新运行会就地更新现有注册，而不是创建重复项 |
| 注册时 HTTP 403 | 检查您的账号是否在 Gemini Enterprise 项目上拥有 Discovery Engine Editor 权限 |
| “Could not fetch agent card” | 验证智能体是否正在运行且 URL 是否正确；对于 Cloud Run，确保已执行 gcloud auth login |
相关技能
/google-agents-cli-deploy— 部署目标、CI/CD 流水线和生产工作流/google-agents-cli-workflow— 开发工作流、编码指南和操作规则/google-agents-cli-scaffold— 使用agents-cli scaffold create/scaffold enhance创建和增强项目
