google-agents-cli-publish

Gemini Enterprise 註冊

必要條件： 已部署的代理。若使用 Agent Runtime，deployment_metadata.json（由 agents-cli deploy 建立）可啟用自動偵測。若使用 Cloud Run 或 GKE，請直接提供代理卡 URL 與旗標。

前置作業

1. 代理必須已部署 — 代理必須正在執行且可連線
2. Gemini Enterprise 應用程式必須存在 — 請先在 Google Cloud 控制台 → Gemini Enterprise → 應用程式中建立一個應用程式，再進行註冊
3. deployment_metadata.json（僅限 Agent Runtime）— 由 agents-cli deploy 自動建立；包含代理執行時期 ID、部署目標及 A2A 旗標

Cloud Run 上 A2A 的必要權限

• 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 — 指令會擷取該卡並進行註冊。

# Cloud Run 上的 A2A
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 代理"

# Agent Runtime 上的 A2A（代理卡 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 建立與增強專案