Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Agent Identity と Auth Manager を使用して、ユーザーに代わって動作する AI エージェントを構築する

1. はじめに

広範な権限を持つ独自の認証情報を持つエージェントは、すべてのユーザーのデータを表示できます。この Codelab では、ログインしたユーザー自身の認証情報を使用してサードパーティ API を呼び出すエージェントを構築します。これにより、そのユーザーが閲覧できるものだけがエージェントに表示され、それ以外のものは表示されなくなります。

このエージェントは、Google Agent Development Kit（ADK）と Gemini Enterprise を使用して構築します。

具体的には、次の条件を満たすデュアルアイデンティティアーキテクチャを設計する方法について学習します。

エージェントが独自の代理として動作する（Agent Identity）: SPIFFE でサポートされている Agent Identity を使用して、エージェントは Auth Manager を呼び出し、テレメトリーを保存し、Google Cloud API を呼び出します。
エージェントがユーザーに代わって動作する（ユーザー委任 ID）: GitHub などの外部リソースにアクセスするために、エージェントは 3 レッグ OAuth（3LO）同意フローをトリガーし、ユーザーの認証情報を使用してツールを安全にクエリします。

デュアル ID アーキテクチャ

このため、次の方法について学習します。

GitHub の Model Context Protocol（MCP）サーバーに接続する ADK エージェントを構築します。
Google Cloud Auth Manager を使用して、エージェントのツールを静的 GitHub PAT（個人用アクセストークン）から 3-legged OAuth（3LO）フローに更新します。
エージェントを Agent Runtime に安全にデプロイし、Agent Identity をプロビジョニングします。
ユーザーに代わってエージェントの ID がトークン保管庫にアクセスできるように IAM ロールを構成します。
Google Cloud の Auth Manager のエンドツーエンドの 3LO フローを理解する。

前提条件

始める前に、次のものが揃っていることを確認してください。

課金を有効にした Google Cloud プロジェクト。
ローカルマシンに Google Cloud SDK（gcloud CLI）がインストールされ、プロジェクトに対して認証されている。バージョン 586.0.0 以降が必要です - gcloud components update を実行します。
Python 3.10 ～ 3.13 がローカルにインストールされている。
uvパッケージマネージャーがインストールされている（pip install uv）。
OAuth アプリケーションを登録してトークンを作成するための GitHub アカウント。GitHub アカウントがない場合は、3-legged OAuth 2.0 をサポートするサードパーティの MCP サーバーを代わりに使用できます。

2. プロジェクトのセットアップ

1. Google Cloud に対して認証を行う

このラボでは、ローカルコマンドラインから Google Cloud に認証して、環境に Agent Runtime へのデプロイ、Agent Identity のプロビジョニング、Auth Manager の構成に必要な権限があることを確認します。

次のコマンドを実行して Google Cloud アカウントにログインし、アプリケーションのデフォルト認証情報（ADC）を構成します。

gcloud auth login
gcloud auth application-default login

2. 必要な Google Cloud サービスを有効にする

このラボを実行するには、Google Cloud プロジェクトで必要な API を有効にします。ターミナルで次のコマンドを実行します。

gcloud services enable \
    agentidentity.googleapis.com \
    agentregistry.googleapis.com \
    aiplatform.googleapis.com \
    apphub.googleapis.com

このコマンドの実行には 1 分ほどかかることがあります。完了すると、コマンドプロンプトに戻り、API が有効になっていることが確認されます。

3. エージェント CLI をインストールしてプロジェクトを設定する

agents-cli は、ADK エージェントを Gemini Enterprise にスキャフォールディング、管理、テスト、デプロイするために使用されるコマンドラインツールです。ローカルにインストールします。

uvx google-agents-cli setup

インストールされたことを確認します。

agents-cli --help

CLI のヘルプメニューに、使用可能なコマンド（deploy、run、status など）が表示されます。

初期プロジェクトのスキャフォールディングを生成します。まずローカルプロトタイプを作成し、後で Agent Runtime のデプロイ用に拡張します。

agents-cli create secure-agent-demo --prototype --yes

これにより、基本的なエージェントコード、依存関係、テストファイルを含む secure-agent-demo ディレクトリが作成されます。

4. 必要な ADK エクストラを追加する

生成された pyproject.toml は google-adk[gcp,otel-gcp] を送信しますが、このエージェントに必要な 2 つの追加機能（GitHub ツールセット用の mcp と、ラボの後半で Auth Manager 用の agent-identity）がありません。secure-agent-demo/pyproject.toml を開き、google-adk 行を次のように変更します。

"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",

次に、以下をインストールします。

cd secure-agent-demo
agents-cli install

3. エージェントを構築してテストする

1. エージェントを作成する

プロジェクト内で、agent.py ファイルのコードを次のコードに置き換えます。

# app/agent.py

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

from app.tools import github_toolset

import os
import google.auth

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

INSTRUCTION = """You are the DevOps Assistant. You help developers list and triage their GitHub issues and pull requests.
Your capabilities: You have a GitHub MCP toolset that you can use to perform actions that the user requests.

Rules:
- NEVER write, update, or delete. You are only allowed read access.
- Act on behalf of the signed-in user.
- If a tool returns an authentication or authorization error, guide the user to sign in.
- NEVER fabricate information. Only report real issues returned by tools.
"""

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=INSTRUCTION,
    tools=[github_toolset()],
)

app = App(
    root_agent=root_agent,
    name="app",
)

このファイルでは、エージェントの 3 つの主要コンポーネントを定義します。

システム指示（INSTRUCTION）: ペルソナを設定し、アシスタントを GitHub トリアージに限定し、厳格な安全ルール（読み取り専用アクセス、エラー発生時のユーザー認証のガイドなど）を適用します。
エージェント構成（root_agent）: gemini-3.8-flash モデルを使用して ADK Agent をインスタンス化し、HTTP 再試行ロジックを構成して、GitHub ツールセットをエージェントに装備します。
アプリラッパー（app）: ルートエージェントを ADK App コンテナにカプセル化し、Agent Runtime にデプロイできるようにします。

2. GitHub MCP ツールを追加する

エージェントは Model Context Protocol（MCP）を介して GitHub に接続します。app/ フォルダに tools.py という名前の新しいファイルを作成して、MCP ゲートウェイ接続パラメータを登録します。次のコードをコピーして貼り付けます。

# app/tools.py

from __future__ import annotations
import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")

def github_toolset() -> McpToolset:
    """Returns the McpToolset connecting to the public GitHub Copilot MCP gateway."""
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=GITHUB_MCP_URL,
            headers={
                "Authorization": f"Bearer {GITHUB_TOKEN}",
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        )
    )

この関数は、GitHub の MCP サーバーを呼び出すツールを作成します。

MCP ツールセット（McpToolset）: GitHub の機能を呼び出し可能なエージェントツールとして動的に検出して登録します。
接続パラメータ（StreamableHTTPConnectionParams）: ツールセットを GitHub の公開 MCP ゲートウェイに指定します。
Authorization ヘッダー: GITHUB_TOKEN を Bearer トークンとして挿入し、トランスポートレイヤで読み取り専用モード（X-MCP-Readonly: true）を直接適用します。

3. GitHub PAT（個人アクセストークン）を使用してローカルでテストする

静的認証情報を使用してエージェントをローカルで実行するには:

GitHub 個人アクセストークンを作成します。リポジトリへの読み取りアクセス権を付与します。そうしないと、エージェントは一般公開データのみを表示でき、次のプロンプトは何も返しません。

環境で設定します。

export GITHUB_TOKEN="your_github_pat_here"

secure-agent-demo フォルダに移動します。実行:
```
cd secure-agent-demo
agents-cli playground
```
プレイグラウンドインターフェースを開き、プルダウンから「app」フォルダを選択します。チャットボックスに「"Fetch my contributions across my private repositories over the last 6 months"」と入力し、エージェントが GitHub ツールを呼び出して、非公開リポジトリからデータを返すことを確認します。

4. Auth Manager を構成する

静的認証情報（PAT など）をハードコードすると、プロトタイピングには便利ですが、本番環境のアプリケーションが認証情報の漏洩、手動のトークン更新によるダウンタイム、クラウドネイティブのアクセス制御の欠如にさらされます。

この問題を解決するために、Google Cloud は Agent Identity Auth Manager を提供しています。Agent Identity Auth Manager は、認証情報の保護を支援するように設計された認証情報保管庫です。エージェントは、API キーまたは OAuth クライアント ID とシークレットを使用して認証できます。また、エンドユーザーアクセストークンを使用した OAuth 委任を通じて、ユーザーの代わりに認証することもできます。

Auth Manager 内で、特定のサードパーティアプリケーションの認証タイプと認証情報を定義する認証プロバイダを構成します。認証プロバイダはリージョンに固有であり、リージョンはエージェントをデプロイするリージョンと一致している必要があります。エンドツーエンドの Auth Manager ワークフローは次のように動作します。

Auth Manager ワークフロー

動的同意のインターセプト: エージェントがユーザーに代わってツールを実行しようとすると、ADK は Auth Manager で有効な認証情報がすでに存在するかどうかを確認します。存在しない場合、Auth Manager は 3-legged OAuth（3LO）同意フローを開始するための認証 URL を返します。
Secure Vault Storage: エンドユーザーがアプリケーションを承認すると、Auth Manager は OAuth コールバックを自動的にインターセプトし、結果として得られたユーザーアクセストークンと更新トークンを安全な Google 管理の認証情報 Vault に保存します。
トークンライフサイクルの自動化: Auth Manager は、トークンの有効期限とローテーションをバックグラウンドで完全に管理するため、トークンの手動更新ロジックやダウンタイムは不要です。
シークレットなしのツール実行: 後続のアクションでは、エージェント（SPIFFE Agent Identity を介して認証）が実行時に Auth Manager からユーザーの委任されたアクセストークンを動的にリクエストし、クライアントコードとエージェントコードの両方を完全にシークレットなしの状態に保ちます。

ステップ A: GitHub を認証プロバイダとして構成する

次の gcloud コマンドを実行して、Google Cloud プロジェクトに GitHub 認証プロバイダを作成します。クライアント ID とシークレットは後で指定します。GitHub は、このプロバイダのコールバック URL を認識するまで、クライアント ID とシークレットを発行しません。

gcloud agent-identity auth-providers create github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1" \
    --three-legged-oauth-authorization-url="https://github.com/login/oauth/authorize" \
    --three-legged-oauth-token-url="https://github.com/login/oauth/access_token"

プロバイダの説明を取得して、生成された OAuth リダイレクト URL を取得します。

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1"

フィールドは redirectUrl で、authProviderTypeParams.threeLeggedOauth の下にネストされます。直接読み取るには:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" --location="us-central1" \
    --format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"

https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback のようになります。

ステップ B: GitHub で OAuth アプリを登録する

GitHub の [Developer Settings] ページに移動し、[Register a new OAuth app] をクリックします。
[ホームページの URL] に、フロントエンドアプリケーションの URL を入力します（ローカルプロトタイピングの場合は http://localhost:8501 など）。後で、本番環境のデプロイ済み URL に変更できます。
[Redirect URI] を、前の手順で取得した redirectUrl に設定します。
[Register application] をクリックし、[Generate a new client secret] をクリックして、クライアント ID とクライアントシークレットの両方を保存します。

ステップ C: GitHub 認証情報を認証プロバイダに追加する

プロジェクト ID、クライアント ID、クライアントシークレットを置き換えて、次のコマンドを実行します。

gcloud agent-identity auth-providers update github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --three-legged-oauth-client-id="YOUR_GITHUB_CLIENT_ID" \
    --three-legged-oauth-client-secret="YOUR_GITHUB_CLIENT_SECRET"

コマンドは、clientId が表示された状態でプロバイダをエコーバックします。シークレットはエコーバックされません。

👉 この手順が完了すると、Google Cloud Auth Manager が GitHub OAuth アプリケーションの認証情報で完全に構成され、同意とトークンのライフサイクルを処理する安全な Vault として機能するように Google Cloud が設定されます。

5. PAT トークンを Auth Manager に切り替える

Auth Manager が完全に構成されたので、次はエージェントのツールコードを更新します。app/tools.py を次のコードに置き換えます。

👉 次の OAUTH_PROVIDER_NAME 変数のプロジェクト ID とロケーションを置き換えます。

# app/tools.py

from __future__ import annotations
import os
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# 1. Register the GCP Auth Provider in the global Credential Manager
CredentialManager.register_auth_provider(GcpAuthProvider())

# 2. Replace YOUR_PROJECT_ID with your project ID.
OAUTH_PROVIDER_NAME = "projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider"

# 3. The frontend callback URL where the user is redirected after authorizing GitHub. Resolved from the environment variable.
OAUTH_CONTINUE_URI = os.environ.get(
    "OAUTH_CONTINUE_URI", 
    "http://localhost:8501/validateUserId"
)

def github_toolset() -> McpToolset:
    """Returns the McpToolset using 3LO credentials retrieved via GCP Auth Manager."""
    auth_scheme = GcpAuthProviderScheme(
        name=OAUTH_PROVIDER_NAME,
        # Required to read private repositories. Auth Manager currently supports a
        # single scope for GitHub.
        scopes=["repo"],
        continue_uri=OAUTH_CONTINUE_URI,
    )
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://api.githubcopilot.com/mcp/",
            headers={
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        ),
        auth_scheme=auth_scheme,
    )

ツールコードについて

主な変更点は auth_scheme です。ツールセットに添付すると、エージェントが GitHub を呼び出すたびに、ADK はまず Auth Manager にそのユーザーのトークンを要求します。トークンがまだない場合は、失敗するのではなく、ユーザーにログインを求めるメッセージが表示されます。ハードコードされた GITHUB_TOKEN は完全に削除されました。

6. エージェントを Agent Runtime にデプロイする

GitHub MCP ツールを更新して Auth Manager を使用するようにしたので、次のステップでは、エージェントを Agent Runtimeにデプロイします。Agent Identity を有効にしてデプロイすると、エージェントに一意の SPIFFE ID がプロビジョニングされます。

まず、プロジェクトのデプロイ構成を初期化します。ターミナルで実行します。

agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes

このコマンドは、プロジェクト構造を調べて ADK との互換性を確認し、基盤となるコンテナパッケージング構成を準備して、デフォルトのデプロイ設定が事前に入力された agents-cli-manifest.yaml ファイルをプロジェクトルートに生成します。

👉 新しく作成した agents-cli-manifest.yaml ファイルを開き、region フィールドを us-central1 に更新または確認して、エージェントが認証プロバイダと同じリージョンにデプロイされていることを確認します。

region: "us-central1"

Agent Identity を使用してエージェントをデプロイする

adk deploy agent_engine を使用してデプロイします。これにより、エージェントに独自のエージェント ID（このデプロイに属する一意の SPIFFE ベースの暗号 ID）がプロビジョニングされます。エージェントはこの ID を使用して、Auth Manager や他の Google Cloud サービスを認証します。

👉 これらのコマンドを実行する前に、YOUR_PROJECT_ID を置き換えます。

# Request a SPIFFE-backed Agent Identity for this deployment
echo '{ "identity_type": "AGENT_IDENTITY" }' > app/.agent_engine_config.json

# Generate the dependency list the build will install
uv export --no-emit-workspace --no-hashes --format requirements.txt \
    --output-file app/requirements.txt

uv run adk deploy agent_engine app \
    --project="YOUR_PROJECT_ID" \
    --region="us-central1"

デプロイでは、コンテナのビルドとアップロードに数分かかります。完了すると、CLI はデプロイされたリソース名を出力します。reasoningEngines/ENGINE_ID 値をメモします。この値は、エージェントを承認し、UI クライアントをこの値に指定するために必要です。

Agent Identity を承認する

エージェントがクラウドで実行されるようになったため、Auth Manager に保存されている認証情報にアクセスする権限が必要になります。デフォルトでは、エージェントの SPIFFE ID は外部クラウドリソースにアクセスできません。

次の gcloud コマンドを実行して、認証プロバイダリソースでエージェントの ID に roles/agentidentity.user ロールを付与します。これにより、エージェントはボールトからユーザートークンをリクエストするために必要な権限のみが付与されます。

👉 YOUR_PROJECT_ID、YOUR_ORG_ID、YOUR_PROJECT_NUMBER、YOUR_ENGINE_ID を置き換えます（エンジン ID は上記のデプロイ出力にあります）。

YOUR_ORG_ID を取得するには、次のコマンドを実行します。

gcloud projects get-ancestors $(gcloud config get-value project) \
  --filter="type=organization" \
  --format="value(id)"

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-YOUR_ORG_ID.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/us-central1/reasoningEngines/YOUR_ENGINE_ID"

次に、プロバイダで自分自身のアカウントに同じロールを付与します。次のステップで実行する UI クライアントは、アプリケーションのデフォルト認証情報を使用して認証情報の最終処理 API を呼び出すため、これがないと、同意フローが agentidentity.authProviders.retrieveCredentials で 403 エラーで失敗します。

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="user:YOUR_EMAIL_ADDRESS"

7. 3LO 同意フローについて

エージェントが安全な Agent Identity を使用して Agent Runtime にデプロイされたので、次のステップでは、ユーザーがエージェントとチャットするためのカスタムフロントエンドインターフェースを提供します。さらに重要な点として、Google Cloud Auth Manager では、認証ループを完了するためにクライアントアプリケーションのコールバックハンドラが必要です。

Google Cloud Auth Manager は、ユーザー認証情報を Vault 内で安全に管理しますが、OAuth トークン交換を単独で完了することはできません。3LO ハンドシェイクは、クライアントアプリケーションがギャップを埋めることを前提としています。

ユーザーが GitHub アプリを承認すると、GitHub はユーザーを Agent Identity 認証プロバイダの redirectUrl にリダイレクトします。
Auth Manager は、ユーザーのブラウザのポップアップをクライアントサイドのコールバック URL（continue_uri）にリダイレクトします。
このリダイレクトをインターセプトし、ブラウザの Cookie から nonce を読み取り、Google Cloud の credentials:finalize エンドポイントを呼び出してハンドシェイクを完了するのは、クライアントアプリケーションの責任です。
クライアントが交換を完了すると、Google Cloud はトークンを認証プロバイダの Vault に安全に保存し、エージェントが GitHub ツールを呼び出せるようにします。

このカスタムクライアントがコールバックエンドポイントをホストしていないと、ハンドシェイクが完了せず、Vault は認証情報を保存できません。

インタラクティブな OAuth 3LO フローは複数のレイヤにまたがります。ツールリクエストの実行ライフサイクル全体は次のとおりです。これについては、以下の説明と次の手順で詳しく説明します。

👉 画像をクリックすると拡大します。

ハンドシェイクにおけるクライアントの主な責任

同意チャレンジをリレーする（ステップ 5 ～ 6）: エージェントは、同意 URL と 1 回限りの nonce を含む adk_request_credential を発行します。クライアントはポップアップを開き、nonce を Cookie として保存します。
リダイレクトコールバックをホストする（ステップ 10 ～ 11）: /validateUserId。同意後に Auth Manager がポップアップを送信します。
トークンを確定する（ステップ 12 ～ 14）: リダイレクトからの検証状態とキャッシュに保存されたノンスを組み合わせて credentials:finalize を呼び出し、トークンを Vault に保存します。

独自のクライアントを構築する

このクライアントをラボ用に記述する必要はありません。次のステップで、事前構築されたクライアントを実行します。この機能を独自のアプリケーションに実装する際は、次の 2 つの参照を参考にしてください。

Auth Manager ドキュメントのクライアントサイドアプリケーションを更新する。同意チャレンジの処理と credentials:finalize の呼び出しについて説明しています。
adk-python リポジトリの実行可能なサンプルクライアント。上記の 3 つの責任の完全な実装については、main.py をご覧ください。

8. UI クライアントをローカルで実行する

3LO 同意フローのシーケンス図で説明したように、Auth Manager はブラウザのポップアップをクライアントサイドのコールバックエンドポイントにリダイレクトする必要があります。サンプルクライアントは、/validateUserId でそのエンドポイントをホストします。ローカルで実行してみましょう。

クライアントファイルをローカルにコピーする

adk-python GitHub リポジトリの gcp_auth/client フォルダに移動します。このフォルダには、チャットクライアントコンテナのビルドに必要なアセットが含まれています。

👉 gcp_auth/client のすべてのファイルをローカル環境にコピーします。

main.py: 前のセクションで説明したトークンファイナライズコールバック（/validateUserId）を含む FastAPI アプリケーションスクリプト。
static/: HTML ページが含まれます。

または、フォルダのスパースチェックアウトを行うこともできます。

git clone --filter=blob:none --no-checkout https://github.com/google/adk-python.git
cd adk-python
git sparse-checkout init --cone
git sparse-checkout set contributing/samples/integrations/gcp_auth/client
git checkout

クライアントを実行する

コピーした client フォルダに移動します。

cd adk-python/contributing/samples/integrations/gcp_auth/client

仮想環境を作成し、クライアントの依存関係をインストールします。このフォルダには requirements.txt が含まれており、pyproject.toml は含まれていないため、uv run uvicorn ... 単独では Failed to spawn: uvicorn で失敗します。
```
uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install --python .venv/bin/python -r requirements.txt
```

デプロイしたエージェントをクライアントで指定し、ポート 8501 で起動します。

export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_ID=YOUR_ENGINE_ID

.venv/bin/uvicorn main:app --port 8501

サーバーが正常に起動し、http://localhost:8501 でリッスンしていることを確認します。

9. OAuth フローをテストする

すべてのサービスがデプロイされ、IAM バインディングが構成され、環境変数が設定されたので、安全なエンドツーエンドのユーザー委任認証フローをテストする準備が整いました。

ステップ A: ツールの実行を開始する

ブラウザタブを開き、クライアント URL（http://localhost:8501）に移動します。
左側のペインで、[エージェントタイプ] を Remote Agent Engine に設定します。
Google Cloud プロジェクトとロケーションを入力します。[Load Remote Agents] をクリックします。これにより、プロジェクトにデプロイされたすべてのエージェントが読み込まれます。
プルダウンから適切なエージェントを選択し、設定を保存します。
チャットボックスに次のように入力します。
```
Fetch my contributions across my private repositories over the last 6 months
```
と入力して Enter キーを押します。
チャット UI を確認します。エージェントはまだユーザーセッションの認証情報を持っていないため、認証チャレンジを受け取り、会話スレッドに [認証が必要です] カードが表示されます。

別のブラウザポップアップウィンドウが開き、Google Cloud の Auth Manager を介して GitHub OAuth 認証ページにリダイレクトされます。
リクエストされた権限を確認し、[承認] をクリックします。
GitHub から Google Cloud にリダイレクトされ、ポップアップが localhost コールバック URL /validateUserId にリダイレクトされます。
コールバックサービスは、認証情報のハンドシェイクを処理して完了します。

ステップ C: 再開

ポップアップウィンドウが閉じると、親チャットタブが自動的に閉じられたことを検出します。
フロントエンドは再開ペイロードをエージェントに返送します。
エージェントは、新しく交換されたトークンを Google Cloud Auth Manager から安全に取得し、ユーザーに代わって GitHub MCP ツールを呼び出し、プライベートリポジトリからチャットウィンドウに直接データをストリーミングします。このデータは、エージェントが単独でアクセスできないデータです。

ステップ D: Cloud ログを検査する

トークンの交換と確定が安全に処理されたことを確認するには:

Google Cloud コンソールの [ログエクスプローラ] に移動します。

ノンスの抽出と検証の成功を確認するサーバーログを見つけます。

INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
INFO:secure-agent-client:Successfully finalized auth provider credentials.

Agent Runtime ログを検査する: Agent Platform コンソールで実行ログを直接表示することもできます。
- Agent Runtime コンソールに移動します。
- リストからデプロイしたエージェントをクリックします。
- [Playground] タブに切り替えます。これにより、下部のペインにライブエージェントログが表示され、エージェントの推論ループ、ツールの実行の詳細、トークン取得のライフサイクルがリアルタイムで表示されます。

10. クリーンアップ

Google Cloud で継続的な課金が発生しないようにするには、デプロイしたリソースをクリーンアップします。

# Follow the instructions here to delete the deployed Agent Runtime resource
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents#console_3

# Delete the auth provider
gcloud agent-identity auth-providers delete github-oauth-provider \
    --project=YOUR_PROJECT_ID --location=us-central1

# Note: deleted providers sit in soft-delete for 30 days, and the name is not
# reusable until roughly a day after that. Pick a fresh name if you repeat this lab.

# Optionally, you could also delete your Google Cloud Project
gcloud projects delete YOUR_PROJECT_ID

# Optionally, delete the GitHub PAT Token and the OAuth app: 
# https://github.com/settings/personal-access-tokens

ローカルファイルをクリーンアップする

必要に応じて、ローカル環境を完全にクリーンアップします。

実行中のターミナルで Ctrl+C キーを押して、ローカル uvicorn サーバーを停止します。
このラボで作成したプロジェクトディレクトリを削除します。

# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. 完了

ログインしたユーザーの代わりに動作するエージェントを構築して保護しました。

学習した内容:

エージェントシステム ID: エージェントが独自のアカウント ID で動作し、GCP インフラストラクチャとの安全なインターフェース、テレメトリーログの管理、認証情報ファイナライズ API の呼び出しを行う方法。
ユーザー委任 ID: エージェントが 3 レッグ OAuth（3LO）同意フローをトリガーして、GitHub などの外部プラットフォームでユーザーに代わって操作する権限をリクエストする方法。
安全なツール統合: Google Cloud Auth Manager を使用して ADK エージェントを Model Context Protocol（MCP）サーバーに接続し、ハードコードされたシークレットを使用する代わりにユーザートークンを動的に取得する方法。
IAM ポリシーの構成: Agent Runtime ID と認証プロバイダの独自のアカウントの両方を認可するための、きめ細かい権限バインディングを設定する方法。