google-agents-cli-publish

Gemini 登録

必須： デプロイ済みのエージェント。Gemini プラットフォームの Agent Runtime では、agents-cli deploy で作成される deployment_metadata.json により自動検出が可能です。Cloud Run または GKE の場合は、エージェントカードの URL とフラグを直接指定してください。

前提条件

1. エージェントがデプロイ済みであること — エージェントが実行中で、アクセス可能である必要があります
2. Gemini アプリが存在すること — 登録する前に Google Cloud コンソールで作成してください
3. deployment_metadata.json（Agent Runtime のみ） — agents-cli deploy によって自動的に作成されます。Agent Runtime ID、デプロイ先、A2A フラグ、エージェントのディレクトリが含まれています
4. テキストベースのエージェント — Live／音声（bidi）エージェントは /run_live トランスポートがないため、Gemini アプリではサポートされていません。代わりにテキストベースのエージェントを登録してください。

Cloud Run での A2A に必要な権限

• Cloud Run サービス上で、Discovery Engine サービスアカウント（service-<PROJECT_NUMBER>@gcp-sa-discoveryengine.iam.gserviceaccount.com）に roles/run.servicesInvoker を付与してください。

---

登録モード

A2A 登録

スキャフォールドされたすべてのエージェントは Agent-to-Agent プロトコルを提供します。A2A は Cloud Run と GKE でのデフォルトかつ唯一の登録タイプです（ネイティブに呼び出せる reasoning engine がないため）。--registration-type a2a を使えば、Agent Runtime でも利用できます。Agent Runtime 上の ADK エージェントの場合、Gemini アプリは :streamQuery を介して Agent Runtime をネイティブに呼び出せるため、CLI は A2A の使用を推奨しません。その場合は ADK 登録を優先してください。別のフレームワークで構築されたエージェントにはネイティブに呼び出せる ADK アプリがないため、どのデプロイ先でも A2A が適切なモードとなり、警告が表示されるのは想定どおりです。エージェントカードの 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 プロジェクトのみ。 登録時に :streamQuery を介してエージェントを呼び出すため、エージェントは ADK アプリとして Agent Runtime にデプロイされている必要があります。 別のフレームワーク上のエージェントは A2A 経由で登録するため、Cloud Run または GKE にデプロイし、そこから公開してください。

これは、Agent Runtime 上の ADK エージェントに対するデフォルトかつ推奨される登録方法です。Gemini アプリは reasoning engine リソース上の :streamQuery を介してエージェントをネイティブに呼び出し、エンドツーエンドで認証します。内部では、:streamQuery が AdkApp の streaming_agent_run_with_events メソッドにディスパッチします。ADK の呼び出しをデバッグする場合は、ランタイムの reasoning_engine_stderr ログでこのメソッド名を検索すると、失敗箇所を追跡できます。また、エージェントに OAuth 認証（--authorization-id）が必要な場合も、この方法を使用してください。エージェントは reasoning engine リソース名を直接使って登録されるため、エージェントカードの 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	エージェントの説明
--tool-description	GEMINI_TOOL_DESCRIPTION	ツールの説明（ADK モードのみ。既定値は説明です）
--registration-type	REGISTRATION_TYPE	adk または a2a（Agent Runtime 上の ADK エージェントでは既定で adk、それ以外のすべて（ADK 以外のフレームワークを含む）では既定で a2a）
--agent-card-url	AGENT_CARD_URL	A2A 登録用のエージェントカード 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 として登録する場合）では、Gemini アプリ ID のみを指定すれば十分です。

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

---

Agent Registry（エージェントと MCP サーバー）

Agent Registry（プレビュー）は、Gemini アプリとは別の、Google Cloud 全体のフリートカタログで、エージェントと MCP サーバーを登録できます。 マネージドランタイム（Gemini プラットフォームの Agent Runtime）にデプロイされたエージェントは自動登録されるため、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 の不具合が発生します。SDK をアップグレードして再デプロイし、その後、再登録してください
--registration-type is required	非対話モードでは、deployment_metadata.json が存在しない場合、--registration-type が必要です
「Gemini app ID is required」と表示される	--gemini-app-id を指定するか、環境変数 GEMINI_APP_ID を設定してください
同じエージェントを再公開する	登録は冪等です。再実行すると、重複を作成せず既存の登録をその場で更新します
登録時に HTTP 403 が発生する	Gemini アプリをホストするプロジェクトで、アカウントに Discovery Engine Editor 権限があることを確認してください
Agent Runtime での ADK 呼び出し失敗をデバッグする	Gemini アプリは、AdkApp の streaming_agent_run_with_events メソッドを介してエージェントを呼び出します（ネイティブの :streamQuery コントラクト）。ランタイムの reasoning_engine_stderr ログで streaming_agent_run_with_events を検索し、根本的なエラーを確認してください
「Could not fetch agent card」と表示される	エージェントが実行中で、URL が正しいことを確認してください。Cloud Run の場合は、gcloud auth login が完了していることを確認してください。Live／音声エージェントは A2A カードがドロップされるため公開できません。Gemini アプリは Live エージェントをサポートしていません

---

関連スキル

• /google-agents-cli-deploy — デプロイ先、CI/CD パイプライン、本番環境のワークフロー（Agent Gateway による管理対象のイングレス／エグレスと Semantic Governance の認識についても説明します）
• /google-agents-cli-workflow — 開発ワークフロー、コーディングガイドライン、運用ルール
• /google-agents-cli-scaffold — agents-cli scaffold create／scaffold enhance によるプロジェクトの作成と拡張