目次

1.はじめに
2.利用する認証タイプについて
3.ADC認証設定とRemote Subagentの実行
4.おわりに

1.はじめに

Gemini CLIをマルチモデル化する – Remote SubagentsでMistral AIモデルを呼び出してみた – の記事で Remote Subagents を紹介しました。

外部エージェント（Remote Subagent）を Google Cloud の Cloud Run 上 にデプロイし、ローカルの Gemini CLI にて、そのエージェントの agent_card_url を設定、呼び出せる形としていました。

ただ、この呼び出し先となるエージェントを Cloud Run 上 にデプロイする際、認証設定は無し、つまり URL を知っていれば誰でもアクセスできる状態でした。

本記事では、そのエージェントの認証設定に焦点を当てます。
Remote Subagents の認証機能から Google Application Default Credentials（ADC）を設定し、Cloud Run 上のエージェントをセキュアに呼び出す方法を紹介します。

環境情報

  • macOS：Tahoe 26.3.1
  • Node.js のバージョン（ node --version ）：24.11.1
  • Gemini CLI のバージョン（ gemini --version ）：0.40.0

2.利用する認証タイプについて

Remote Subagents の認証機能ですが、以下の認証タイプがサポートされています。

  • apiKey：静的な API キーを HTTP ヘッダーで送信する
  • http：HTTP 認証（Bearer トークン、Basic 認証など）
  • google-credentials：Google Application Default Credentials（ADC）。アクセストークンまたは ID トークンを自動的に選択する
  • oauth：OAuth 2.0 Authorization Code フロー（PKCE）。ブラウザでの対話型サインインを行う

この中から自身の要件に合う認証タイプを選択します。

ローカルで起動する Gemini CLI から Google Cloud の Cloud Run 上にデプロイした外部エージェントを呼び出すケースでは、公式ドキュメントより google-credentials が推奨されています。
本記事ではこの設定を実施します。

google-credentials を設定する際、エージェントの Markdown ファイルには以下のような auth ブロックを追加します。

---
kind: remote
name: my-gcp-agent
agent_card_url: https://my-agent-XXXXXXXXXX.run.app/.well-known/agent.json
auth:
  type: google-credentials
---

google-credentials は ADC を使い ID トークンを *.run.app ホストに自動送信します。
この ID トークンは呼び出し元の身元を証明するもので、トークンの送信先は *.googleapis.com および *.run.app に限定されています。
これを後述する Cloud Run 側の認証設定と組み合わせることで、認証されたユーザーのみが外部エージェントを呼び出せる構成が実現できます。

ちなみにローカル環境での ADC の設定として、事前に以下コマンドで認証を済ませておく必要があるので実行しておきます。（公式ドキュメントの Setup の Local development 参照）

gcloud auth application-default login

認証タイプについての説明は以上になります。

続いては外部エージェントを google-credentials を通じて呼び出す形を構築し、Gemini CLI にて実行してみます。

3.ADC認証設定とRemote Subagentの実行

事前準備

外部エージェントの作成については Gemini CLIをマルチモデル化する – Remote SubagentsでMistral AIモデルを呼び出してみた – を踏襲し ADK Samples (Python) の LLM Auditor を使用します。
LLM Auditor は文章のファクトチェック機能を持つエージェントです。

コードのコンテナ化については上記過去記事のものを流用する形なので、内容について本記事では省略します。

今後提示していくコマンドの YOUR_PROJECT_ID は仮の値なので、実際に使用するプロジェクト ID に置き換えてください。

サービスアカウントの作成と権限付与

Cloud Run に外部エージェントをデプロイするにあたり、まずサービスアカウントを作成します。

以下コマンドでサービスアカウントの作成と権限付与を行います。

# 専用サービスアカウントの作成
gcloud iam service-accounts create adk-agent-sa \
  --display-name="ADK Agent Service Account" \
  --project=YOUR_PROJECT_ID

# Vertex AI ユーザー権限の付与
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:adk-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Vertex AI ユーザー権限を付与したサービスアカウントを作成しました。

Cloud Run をデプロイする際、このサービスアカウントを指定する形とします。

ちなみに roles/aiplatform.user は広範な権限を持つロールです。
最小権限の原則を遵守するなら権限を絞るべきですが、本記事の趣旨は Remote Subagents の ADC 認証の設定にあるので、この権限のまま進めます。
IAM の権限周りに興味のある方は IAM を使用した Vertex AI のアクセス制御 を参照ください。

続いて Cloud Run のデプロイを行います。

Cloud Runデプロイの実行

過去記事通り2回デプロイを行います。（1度目のデプロイで Service URL を取得し、2回目のデプロイではデプロイコマンドのオプションに Service URL の環境変数指定を追加します。この Service URL ですが Gemini CLI からの呼び出し先情報となる AgentCard 作成に必要となるので設定します）

デプロイコマンドについて、過去記事との差分は以下の2点です。

  • --allow-unauthenticated を --no-allow-unauthenticated とする
  • --service-account オプションを追加する（作成したサービスアカウントを指定する）

--no-allow-unauthenticated オプションを指定することで、デプロイした Cloud Run サービスは未認証のリクエストを拒否する形となり、--service-account オプションを指定することで、デフォルトのサービスアカウントでなく、指定のサービスアカウントが Cloud Run サービスに設定されます。

1回目のデプロイを実行します。（コマンドは /Users/xxx/Documents/adk-samples/python で実行しています）

gcloud run deploy my-adk-agent-2026 \
  --source agents/llm-auditor \
  --project=YOUR_PROJECT_ID \
  --region=asia-northeast1 \
  --no-allow-unauthenticated \
  --port=8000 \
  --service-account=adk-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com

デプロイが完了すると Service URL が出力されます。（URL は一部マスキングしております）

Done.                                                                                                                       
〜〜省略〜〜
Service URL: https://my-adk-agent-2026-XXXXXXXXXX.asia-northeast1.run.app

この Service URL を環境変数指定し2回目のデプロイを実行します。

gcloud run deploy my-adk-agent-2026 \
  --source agents/llm-auditor \
  --project=YOUR_PROJECT_ID \
  --region=asia-northeast1 \
  --no-allow-unauthenticated \
  --port=8000 \
  --service-account=adk-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --set-env-vars SERVICE_URL=https://my-adk-agent-2026-XXXXXXXXXX.asia-northeast1.run.app

Google Cloud のプロジェクトに入り、ビルドに成功、Cloud Run のサービスが作成されていることを確認しておきます。（2つビルドが成功しており、サービスは認証設定が Require authentication で作成されています）


Cloud Run のデプロイはこれで以上です。
続いて Gemini CLI 側の設定と実行に進みます。

Gemini CLIのRemote Subagents設定と実行

外部 AI エージェント（Remote Subagent）の用意ができました。
今回は google-credentials を設定の上、そのエージェントを呼び出すため、呼び出し元のアカウント（ローカルの gcloud 認証ユーザー）に roles/run.invoker を付与します。

gcloud run services add-iam-policy-binding my-adk-agent-2026 \
  --region=asia-northeast1 \
  --member="user:ローカルの gcloud 認証ユーザー" \
  --role="roles/run.invoker" \
  --project=YOUR_PROJECT_ID

続いて Gemini CLI 側の設定です。
~/.gemini/agents/ に Markdown ファイル作成します。

agent_card_url に設定する URL は Service URL に /.well-known/agent-card.json を付与したものになります。
auth ブロックには type: google-credentials を設定します。

$ vi my-adk-agent.md
---
kind: remote
name: my-adk-agent-2026
agent_card_url: https://my-adk-agent-2026-xxxxxxxxxxx.asia-northeast1.run.app/.well-known/agent-card.json
auth:
  type: google-credentials
---

my-adk-agent.md が作れたので、Gemini CLI を立ち上げ /agents list コマンドを実行します。

Remote Agents が1つ表示されています。
これを実行してみます。

ユーザープロンプトに以下を入力し実行します。
入力内容として Cloud Run に関する誤った情報を記載しているので、それを指摘する回答が返されるはずです。

@my-adk-agent-2026 Cloud Runは常に1インスタンス以上が起動しているため、アイドル状態でも課金が発生します。また、Cloud RunはVPC接続が必須であり、インターネット公開はできません。


Subagent が呼び出され、期待通りユーザープロンプトに入力した Cloud Run に関する記述の正確性確認と修正された内容が表示されました。

念の為 Subagent を使った応答なのか Gemini CLI 上で尋ねてみたところ、Subagent にタスクを委譲し、その結果を受け取り回答しているとのことでした。

Google Cloud のプロジェクトに入りログも見てみます。

agent-card.json に対する GET の 403、その次に 200 が確認できます。
公式ドキュメントの Agent card fetching and auth によると、まず認証なしで agent card を呼び出し、そこで 401 もしくは 403 を返した場合、認証ありで再試行となるようです。

POST の 200 のログも確認できますが、これはリクエストを受け取り外部エージェントが実行され応答を返したことを示すものとなります。

最後に ~/.gemini/agents/my-adk-agent.md から auth ブロックを削除し、Gemini CLI を立ち上げてみます。

$ vi my-adk-agent.md
---
kind: remote
name: my-adk-agent-2026
agent_card_url: https://my-adk-agent-2026-xxxxxxxxxxx.asia-northeast1.run.app/.well-known/agent-card.json
---

auth ブロックを削除したことで、認証無しで認証が必要な Cloud Run サービスにアクセスするので弾かれるはずです。

Gemini CLI を立ち上げると以下のメッセージが表示されました。

Failed to load remote agent: Failed to fetch Agent Card とのことで、認証が必要な Cloud Run サービスに認証なしで読み込みを行い、読み込み失敗、403エラーとなることが確認できました。

4.おわりに

Remote Subagents の認証機能として google-credentials（ADC）を設定し、Cloud Run 上の外部エージェントをセキュアに呼び出す構成を構築しました。

ポイントとしては Cloud Run 側に --no-allow-unauthenticated を設定、Gemini CLI 側はエージェントの Markdown ファイルに auth ブロックを追加するところとなります。

Remote Subagents の認証機能には apiKey、http、oauth といった認証タイプも用意されています。
外部エージェントのホスト先や要件に応じ適切な認証タイプを選択、設定してみてください。