Back to Details

google-agents-cli-publish

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Gemini Enterprise Registration

Gemini Enterprise 注册

Requires: A deployed agent. For Agent Runtime, 
deployment_metadata.json
(created by 
agents-cli deploy
) enables auto-detection. For Cloud Run or GKE, provide the agent card URL and flags directly.
要求： 已部署的Agent。对于Agent Runtime，
deployment_metadata.json
（由
agents-cli deploy
创建）支持自动检测。对于Cloud Run或GKE，请直接提供Agent卡片URL和参数。

Prerequisites

前提条件

  1. Agent must be deployed — the agent must be running and reachable
  2. Gemini Enterprise app must exist — Create one in Google Cloud Console → Gemini Enterprise → Apps before registering
  3. deployment_metadata.json
     (Agent Runtime only) — Created automatically by 
    agents-cli deploy
    ; contains the agent runtime ID, deployment target, and A2A flag
  1. Agent必须已部署 —— Agent必须处于运行状态且可访问
  2. Gemini Enterprise应用必须已存在 —— 注册前请在Google Cloud控制台 → Gemini Enterprise → 应用中创建一个应用
  3. deployment_metadata.json
    （仅适用于Agent Runtime）—— 由
    agents-cli deploy
    自动创建；包含Agent Runtime ID、部署目标和A2A参数

Required Permissions for A2A on Cloud Run

A2A在Cloud Run上的必要权限

  • roles/run.servicesInvoker
     granted to the Discovery Engine service account (
    service-<PROJECT_NUMBER>@gcp-sa-discoveryengine.iam.gserviceaccount.com
    ) on the Cloud Run service.
  • 需为Discovery Engine服务账号（
    service-<PROJECT_NUMBER>@gcp-sa-discoveryengine.iam.gserviceaccount.com
    ）授予Cloud Run服务的**
    roles/run.servicesInvoker
    **角色。

Registration Modes

注册模式

ADK Registration (default)

ADK注册（默认）

For standard ADK agents deployed to Agent Runtime. The agent is registered directly via its reasoning engine resource name.
bash
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 "My Agent" \
  --description "Handles customer queries" \
  --tool-description "Answers questions about products"
适用于部署到Agent Runtime的标准ADK Agent。Agent将通过其推理引擎资源名称直接注册。
bash
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 "My Agent" \
  --description "Handles customer queries" \
  --tool-description "Answers questions about products"

A2A Registration

A2A注册

For agents using the Agent-to-Agent protocol. Requires an agent card URL — the command fetches the card and registers it.
bash
undefined
适用于使用Agent-to-Agent协议的Agent。需要Agent卡片URL —— 命令将获取该卡片并完成注册。
bash
undefined

A2A on Cloud Run

A2A on 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 "My A2A Agent"
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 "My A2A Agent"

A2A on Agent Runtime (card URL is auto-constructed from metadata)

A2A on Agent Runtime (card URL is auto-constructed from metadata)

agents-cli publish gemini-enterprise
--registration-type a2a
--gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app

---
agents-cli publish gemini-enterprise
--registration-type a2a
--gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app

---

Programmatic Mode (CI/CD)

程序化模式（CI/CD）

The command is non-interactive by default — pass all required values via flags or environment variables. This makes it safe for CI/CD pipelines.
命令默认是非交互式的 —— 通过参数或环境变量传递所有必填值。这使其可安全用于CI/CD流水线。

Via flags

通过参数

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

Via environment variables

通过环境变量

Every flag has an env var alternative:
bash
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="Production Agent"
export GEMINI_DESCRIPTION="Handles customer queries"

agents-cli publish gemini-enterprise
每个参数都有对应的环境变量替代方案：
bash
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="Production Agent"
export GEMINI_DESCRIPTION="Handles customer queries"

agents-cli publish gemini-enterprise

Interactive Mode (
--interactive
)

交互式模式（
--interactive
）

Pass 
--interactive
(or 
-i
) to be guided through any missing values with interactive prompts. The command will list available Gemini Enterprise apps, offer to auto-detect the agent runtime ID from metadata, and prompt for display name and description.
bash
agents-cli publish gemini-enterprise --interactive
传递
--interactive
（或
-i
）参数，将通过交互式提示引导您补充任何缺失的值。命令会列出可用的Gemini Enterprise应用，提供从元数据自动检测Agent Runtime ID的选项，并提示输入显示名称和描述。
bash
agents-cli publish gemini-enterprise --interactive

Complete Flag Reference

完整参数参考

FlagEnv VarDescription
--agent-runtime-id
AGENT_RUNTIME_ID
Agent Runtime resource name (auto-detected from 
deployment_metadata.json
)
--gemini-enterprise-app-id
ID
or 
GEMINI_ENTERPRISE_APP_ID
Gemini Enterprise app full resource name
--display-name
GEMINI_DISPLAY_NAME
Display name in Gemini Enterprise
--description
GEMINI_DESCRIPTION
Agent description
--tool-description
GEMINI_TOOL_DESCRIPTION
Tool description (ADK mode only, defaults to description)
--registration-type
REGISTRATION_TYPE
adk
or 
a2a
(auto-detected from metadata if not set)
--agent-card-url
AGENT_CARD_URL
Agent card URL for A2A registration
--deployment-target
DEPLOYMENT_TARGET
agent_runtime
, 
cloud_run
, or 
gke
(affects A2A auth method)
--project-id
GOOGLE_CLOUD_PROJECT
GCP project ID for billing
--project-number
PROJECT_NUMBER
GCP project number (used for Gemini Enterprise lookup)
--authorization-id
GEMINI_AUTHORIZATION_ID
OAuth authorization resource name
--metadata-file
—Path to deployment metadata (default: 
deployment_metadata.json
)
--interactive
/ 
-i
—Enable interactive prompts
参数环境变量描述
--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
Agent描述
--tool-description
GEMINI_TOOL_DESCRIPTION
工具描述（仅ADK模式，默认与描述相同）
--registration-type
REGISTRATION_TYPE
adk
或 
a2a
（若未设置则从元数据自动检测）
--agent-card-url
AGENT_CARD_URL
A2A注册用的Agent卡片URL
--deployment-target
DEPLOYMENT_TARGET
agent_runtime
, 
cloud_run
, or 
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
—启用交互式提示

Auto-Detection from Metadata

从元数据自动检测

When 
deployment_metadata.json
exists, the command automatically:
  • Reads the agent runtime ID (
    remote_agent_runtime_id
    )
  • Detects the registration type (
    is_a2a
    flag)
  • Constructs the agent card URL for A2A agents on Agent Runtime
  • Determines the deployment target for authentication
This means that for the simplest case (ADK agent on Agent Runtime), you only need to provide the Gemini Enterprise app ID:
bash
agents-cli publish gemini-enterprise \
  --gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app
当
deployment_metadata.json
存在时，命令会自动：
  • 读取Agent Runtime ID（
    remote_agent_runtime_id
    ）
  • 检测注册类型（
    is_a2a
    参数）
  • 为Agent Runtime上的A2A Agent构建Agent卡片URL
  • 确定用于认证的部署目标
这意味着在最简单的场景（部署到Agent Runtime的ADK Agent）下，您只需提供Gemini Enterprise应用ID即可：
bash
agents-cli publish gemini-enterprise \
  --gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app

SDK Compatibility

SDK兼容性

Agent Runtime deployments may encounter "Session not found" errors with 
google-cloud-aiplatform
versions <= 1.128.0. In interactive mode (
--interactive
), the command checks the SDK version from 
uv.lock
and offers to upgrade. In programmatic mode, ensure your SDK is up to date before registering.
当
google-cloud-aiplatform
版本 <= 1.128.0时，Agent Runtime部署可能会遇到“Session not found”错误。在交互式模式（
--interactive
）下，命令会从
uv.lock
检查SDK版本，并提供升级选项。在程序化模式下，请确保注册前SDK已更新至最新版本。

Troubleshooting

故障排查

IssueSolution
"Session not found" after registrationSDK version issue — upgrade 
google-cloud-aiplatform
(see SDK Compatibility above), redeploy, then re-register
--registration-type is required
Non-interactive mode needs 
--registration-type
when no 
deployment_metadata.json
exists
"Gemini Enterprise App ID is required"Provide 
--gemini-enterprise-app-id
or set the 
ID
/ 
GEMINI_ENTERPRISE_APP_ID
env var
"Agent already registered"The command automatically updates the existing registration — this is not an error
HTTP 403 on registrationCheck that your account has Discovery Engine Editor permissions on the Gemini Enterprise project
"Could not fetch agent card"Verify the agent is running and the URL is correct; for Cloud Run, ensure 
gcloud auth login
is done
问题解决方案
注册后出现“Session not found”SDK版本问题 —— 升级
google-cloud-aiplatform
（参见上述SDK兼容性部分），重新部署后再重新注册
需要
--registration-type
参数		当不存在
deployment_metadata.json
时，非交互式模式需要指定
--registration-type
“Gemini Enterprise应用ID是必填项”提供
--gemini-enterprise-app-id
参数或设置
ID
/ 
GEMINI_ENTERPRISE_APP_ID
环境变量
“Agent已注册”命令会自动更新现有注册 —— 这不是错误
注册时出现HTTP 403错误检查您的账号是否在Gemini Enterprise项目中拥有Discovery Engine Editor权限
“无法获取Agent卡片”确认Agent正在运行且URL正确；对于Cloud Run，请确保已完成
gcloud auth login

Related Skills

相关Skill

  • /google-agents-cli-deploy
    — Deployment targets, CI/CD pipelines, and production workflows
  • /google-agents-cli-workflow
    — Development workflow, coding guidelines, and operational rules
  • /google-agents-cli-scaffold
    — Project creation and enhancement with 
    agents-cli scaffold create
    / 
    scaffold enhance
  • /google-agents-cli-deploy
    —— 部署目标、CI/CD流水线和生产工作流
  • /google-agents-cli-workflow
    —— 开发工作流、编码指南和操作规则
  • /google-agents-cli-scaffold
    —— 使用
    agents-cli scaffold create
    / 
    scaffold enhance
    创建和增强项目