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

1. はじめに

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

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

具体的には、次のようなデュアル ID アーキテクチャを設計する方法を学習します。

  1. エージェントが自身の代理として動作する(Agent Identity): SPIFFE を基盤とする Agent Identity を使用して、エージェントは Auth Manager を呼び出し、テレメトリーを保存し、Google Cloud API を呼び出します。
  2. エージェントがユーザーに代わって動作する(ユーザー委任 ID): GitHub などの外部リソースにアクセスするために、エージェントは 3-legged OAuth(3LO)同意フローをトリガーし、ユーザーの認証情報を使用してツールに安全にクエリを実行します。

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

この目標を達成するために、次の方法を学びます。

  1. GitHub の Model Context Protocol(MCP)サーバーに接続する ADK エージェントを構築する。
  2. エージェントのツールを、静的な GitHub PAT(個人用アクセス トークン)から、Google Cloud Auth Manager を使用する 3-legged OAuth(3LO)フローに更新します。
  3. エージェントを Agent Runtime に安全にデプロイし、Agent Identity をプロビジョニングする。
  4. エージェントの ID がユーザーに代わってトークン ボールトにアクセスできるように IAM ロールを構成する。
  5. 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 アカウントにログインし、アクティブなプロジェクトを設定して(YOUR_PROJECT_ID は Google Cloud プロジェクト ID に置き換えます)、アプリケーションのデフォルト認証情報(ADC)を構成します。

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login

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

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

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

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

3. Agents 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 に、不足している 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. エージェントを作成する

プロジェクト内で、secure-agent-demo/app/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 に接続します。secure-agent-demo/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 ゲートウェイにポイントします。
  • 認可ヘッダー: GITHUB_TOKEN を署名なしトークンとして挿入し、トランスポート層で読み取り専用モード(X-MCP-Readonly: true)を直接適用します。

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

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

  1. GitHub の [Personal Access Tokens] ページで、きめ細かい個人アクセス トークンを作成します。
    • [Generate new token] をクリックし、トークンに名前を付けます。
    • [Repository access] で、[All repositories] を選択します(または、テストする特定のリポジトリを選択します)。
    • [Permissions] > [Repositories] で、[+Add permissions] をクリックし、[Contents]、[Issues]、[pull リクエスト] を [Read-only] に設定します([Metadata] は自動的に [Read-only] に設定されます)。
    • [Generate token] をクリックし、生成されたトークン値をコピーします。(または、個人用アクセス トークン(クラシック)を使用する場合は、repo スコープを選択します)。
  2. 環境で設定します。
    export GITHUB_TOKEN="your_github_pat_here"
    
  3. secure-agent-demo フォルダに移動し(まだ移動していない場合)、ローカル プレイグラウンドを起動します。
    cd secure-agent-demo
    agents-cli playground
    
  4. プレイグラウンド インターフェースを開き、プルダウンからフォルダ app を選択します。チャットボックスで、"Get the last 2 GitHub issues reported against my name" や "List my 3 most recently updated repositories" などのターゲットを絞ったプロンプトを試し、エージェントが GitHub MCP ツールセットを呼び出して GitHub データを返すことを確認します。エージェントが実際に PAT トークンを使用してユーザーに代わってアクションを実行しているかどうかをテストするには、プライベート リポジトリやコントリビューションについて質問してみてください。

4. Auth Manager を構成する

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

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

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

Auth Manager のワークフロー

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

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

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

gcloud agent-identity auth-providers create github-oauth-provider \
    --project="YOUR_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="YOUR_PROJECT_ID" \
    --location="us-central1"

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

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="YOUR_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 アプリを登録する

  1. GitHub のデベロッパー設定ページに移動し、左側のサイドバーで [OAuth Apps] を選択して、[New OAuth App](または、まだ作成していない場合は [Register a new application])をクリックします。
  2. OAuth 申請フォームのフィールドに入力します。
    • アプリケーション名: アプリケーションの名前を入力します(例: secure-agent-demo)。
    • ホームページの URL: フロントエンド アプリケーションの URL を入力します(ローカル プロトタイピングの場合は http://localhost:8501。本番環境でデプロイされた URL に更新できます)。
    • Application description: 省略可(空白のままにしてもかまいません)。
    • Authorization callback URL(リダイレクト URI): 手順 A で取得した redirectUrl を貼り付けます。
    • Enable Device Flow: チェックボックスをオフのままにします。
  3. [Register application] をクリックします。
  4. 表示されたアプリケーション ページで、クライアント ID をコピーし、[Generate a new client secret] をクリックして、生成されたクライアント シークレットをコピーします。両方の値を保存します。次のステップで YOUR_GITHUB_CLIENT_ID と YOUR_GITHUB_CLIENT_SECRET として使用します。

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

YOUR_PROJECT_ID、YOUR_GITHUB_CLIENT_ID、YOUR_GITHUB_CLIENT_SECRET を実際の値に置き換えて、次のコマンドを実行します。

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 アプリケーションの認証情報で完全に構成され、Google Cloud が同意とトークンのライフサイクルを処理する安全なボルトとして機能するようになります。

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

Auth Manager の構成が完了したら、次のステップとしてエージェントのツールコードを更新します。secure-agent-demo/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 がプロビジョニングされます。

プロジェクトのデプロイ構成を初期化します。ターミナルが secure-agent-demo プロジェクトのルート ディレクトリにあることを確認してから、次のコマンドを実行します。

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"

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

adk deploy agent_engine を使用してデプロイする。これにより、エージェントに独自の Agent Identity(このデプロイに属する、SPIFFE に基づく一意の暗号 ID)がプロビジョニングされます。エージェントは、この ID を使用して Auth Manager やその他の Google Cloud サービスに対して認証を行います。

👉 secure-agent-demo ディレクトリから、YOUR_PROJECT_ID を置き換えて次のコマンドを実行します。

# Write a config file inside the `app/` folder instructing Agent Runtime to provision 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 クライアントをエージェントにポイントするために必要です。

エージェント ID を認可する

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

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

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

# Get YOUR_PROJECT_NUMBER
gcloud projects describe $(gcloud config get-value project) \
  --format="value(projectNumber)"

次に、認証プロバイダに IAM ポリシーをバインドします(YOUR_PROJECT_ID と --member プリンシパルを置き換えます)。

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"

👉 デプロイされたエージェントの完全な --member="principal://..." 値は、Google Cloud コンソールから取得することもできます。Agent Runtime コンソールに移動し、デプロイされたエージェントを選択して、[Identity] タブに移動し、完全な principal://... 文字列を直接コピーします。

次に、プロバイダで自分のアカウントに同じロールを付与します。次のステップで実行する 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 同意フローについて

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

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

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

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

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

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

3-Legged OAuth シーケンス フロー

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

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

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

このラボでは、このクライアントを作成する必要はありません。次のステップで、事前作成済みのクライアントを実行します。この機能を独自のアプリケーションに実装する際は、次の 2 つのリファレンスを参考にしてください。

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

3LO 同意フローのシーケンス図に示すように、Auth Manager はブラウザ ウィンドウをクライアントサイドのコールバック エンドポイントにリダイレクトします。adk-python リポジトリのサンプル クライアントは、そのエンドポイントを /validateUserId でホストします。次の手順でダウンロードしてローカルで実行します。

クライアント ファイルをダウンロードする

adk-python の contributing/samples/integrations/gcp_auth/client ディレクトリには、次の 3 つの主要なアセットが含まれています。

  • main.py: デプロイされた Agent Engine に接続し、/validateUserId コールバック エンドポイントをホストして OAuth トークンを確定する FastAPI バックエンド。
  • static/: ブラウザのチャット UI の HTML ファイルと JavaScript ファイル。
  • requirements.txt: クライアント サーバーの実行に必要な Python パッケージ。

adk-python は大規模なリポジトリであるため、Git のスパース チェックアウト機能を使用して contributing/samples/integrations/gcp_auth/client フォルダのみをダウンロードします。

  1. まず、secure-agent-demo から 1 つ上のディレクトリに移動して、クライアントを兄弟フォルダにクローンします。
    cd ..
    
  2. 次のコマンドを実行して、すべてのファイルをダウンロードせずにリポジトリ メタデータをクローンし(--no-checkout)、チェックアウト パスを contributing/samples/integrations/gcp_auth/client に制限して、そのフォルダのみをチェックアウトします。
    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
    

クライアントを実行する

  1. 先ほど移動した adk-python ディレクトリ内から、client フォルダに移動します。
    cd contributing/samples/integrations/gcp_auth/client
    
  2. Python 仮想環境を作成して有効にし、requirements.txt からクライアントの依存関係をインストールします。
    uv venv --python 3.13 .venv
    source .venv/bin/activate
    uv pip install --python .venv/bin/python -r requirements.txt
    
  3. クライアントが Google Cloud プロジェクト、リージョン(us-central1)、デプロイされた Agent Engine ID(YOUR_ENGINE_ID)を指すように環境変数を設定し、ポート 8501 でローカル FastAPI サーバーを起動します。
    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
    
  4. サーバーが正常に起動し、http://localhost:8501 でリッスンしていることを確認します。

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

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

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

  1. ブラウザタブを開き、クライアント URL(http://localhost:8501)に移動します。
  2. [構成設定] の左側のペインで、[エージェント タイプ] を Remote Agent (Vertex AI)(または Remote Agent Engine)に設定します。
  3. Google Cloud のプロジェクト ID とロケーション(us-central1)を入力し、[リモート エージェントを読み込む] をクリックします。これにより、プロジェクトにデプロイされたエージェントが読み込まれます。
  4. [Select Engine] プルダウンからデプロイした app エージェントを選択し、[Save & Apply Settings] をクリックします。
  5. チャット ボックスに、ターゲット クエリ(最近の問題やリポジトリの取得など)を入力します。
    Get the last 2 GitHub issues reported against my name
    
    (または "List my 3 most recently updated repositories")と入力して Enter キーを押します。
  6. チャット UI を確認します。エージェントにはユーザー セッションの認証情報がまだないため、認証チャレンジを受け取り、会話スレッドに [Authentication Required] カードを表示します。
  1. 別のブラウザのポップアップ ウィンドウが開き、Google Cloud の Auth Manager を介して GitHub OAuth 認可ページにリダイレクトされます。
  2. リクエストされた権限を確認し、[承認] をクリックします。
  3. GitHub は Google Cloud にリダイレクトし、Google Cloud はポップアップを localhost コールバック URL /validateUserId にリダイレクトします。
  4. コールバック サービスは、認証情報のハンドシェイクを処理して完了します。

ステップ C: 再開

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

ステップ D: Cloud Logging を調べる

トークンの交換とファイナライズが安全に処理されたことを確認するには:

  1. Google Cloud コンソールのログ エクスプローラに移動します。
  2. ノンスの抽出と検証の成功を確認するサーバーログを見つけます。
    INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
    INFO:secure-agent-client:Successfully finalized auth provider credentials.
    
  3. 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

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

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

  1. 実行中のターミナルで Ctrl+C キーを押して、ローカルの uvicorn サーバーを停止します。
  2. このラボで作成したプロジェクト ディレクトリを削除します。
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. 完了

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

学習した内容:

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

関連情報