使用 Agent Identity 和驗證管理員,建構可代表使用者執行的 AI 代理

1. 簡介

如果代理程式有自己的憑證,且具備廣泛權限,就能查看所有人的資料。在本程式碼實驗室中,您將建構一個代理,使用已登入使用者的憑證呼叫第三方 API,因此該代理只能看到該使用者能看到的內容。

您將使用 Google Agent Development Kit (ADK) 和 Gemini Enterprise 建構。

具體來說,您將瞭解如何設計雙重身分架構,其中:

  1. 代理以自身身分 (代理身分) 執行操作:代理使用 SPIFFE 支援的代理身分,叫用 Auth Manager、儲存遙測資料,並呼叫 Google Cloud API。
  2. 代理代表使用者執行操作 (使用者委派身分):如要存取 GitHub 等外部資源,代理會觸發三腳 OAuth (3LO) 同意流程,使用使用者的憑證安全查詢工具。

雙重身分架構

為達成此目標,您將學習如何:

  1. 建構 ADK 代理,連至 GitHub 的 Model Context Protocol (MCP) 伺服器。
  2. 使用 Google Cloud Auth Manager,將代理工具從靜態 GitHub PAT (個人存取權杖) 更新為三足式 OAuth (3LO) 流程。
  3. 將代理安全地部署至 Agent Runtime,並佈建代理身分。
  4. 設定 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)。
  • GitHub 帳戶:用於註冊 OAuth 應用程式及建立權杖。如果沒有 GitHub 帳戶,可以改用任何支援 3-legged OAuth 2.0 的第三方 MCP 伺服器。

2. 專案設定

1. 向 Google Cloud 驗證

在本實驗室中,請從本機指令列向 Google Cloud 驗證身分,確保環境具備必要權限,可部署至 Agent Runtime、佈建代理身分,以及設定 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 服務

在 Google Cloud 雲端專案中啟用必要的 API,以便執行本實驗室。在終端機中執行下列指令:

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

這個指令可能需要一分鐘才能執行完畢。完成後,系統會返回命令提示字元,確認 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 中,新增缺少的兩個額外項目: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",
)

這個檔案定義了代理的三個主要元件:

  • 系統指令 (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 的個人存取權杖頁面,建立精細的個人存取權杖:
    • 點選「Generate new token」,然後為權杖命名。
    • 在「Repository access」下方,選取「All repositories」 (或選取要測試的特定存放區)。
    • 在 Permissions > Repositories 下方,按一下 +Add permissions,然後將 Contents、Issues 和 提取要求 設為 Read-only (Metadata 會自動設為 Read-only)。
    • 按一下「Generate token」,然後複製產生的權杖值。(或者,如果您使用個人存取權杖 (傳統),請選取 repo 範圍。)
  2. 在環境中設定:
    export GITHUB_TOKEN="your_github_pat_here"
    
  3. 前往 secure-agent-demo 資料夾 (如果尚未進入),然後啟動本機 Playground:
    cd secure-agent-demo
    agents-cli playground
    
  4. 開啟 Playground 介面,然後從下拉式選單中選取資料夾 app。在對話方塊中,嘗試輸入 "Get the last 2 GitHub issues reported against my name" 或 "List my 3 most recently updated repositories" 等特定提示詞,並確認代理會呼叫 GitHub MCP 工具集,並傳回 GitHub 資料。如要測試代理是否確實使用您的 PAT 權杖代您採取行動,請詢問代理有關私人存放區或貢獻的問題。

4. 設定驗證管理員

雖然在原型設計階段,硬式編碼靜態憑證 (例如 PAT) 很方便,但會使正式版應用程式面臨憑證外洩、手動更新權杖停機,以及缺乏雲端原生存取控管等風險。

為解決這個問題,Google Cloud 提供 Agent Identity 驗證管理工具。Agent Identity 驗證管理工具是憑證保管箱,可協助保護憑證。代理可使用 API 金鑰或 OAuth 用戶端 ID 和密鑰進行驗證,或使用使用者存取權杖,透過 OAuth 委派代表使用者進行驗證。

在 Auth Manager 中,您可以設定驗證提供者,定義特定第三方應用程式的驗證類型和憑證。驗證提供者為區域性,且區域必須與代理部署的區域相符。Auth Manager 的端對端工作流程如下:

驗證管理員工作流程

  1. 動態同意聲明攔截:代理嘗試代表使用者執行工具時,ADK 會檢查 Auth Manager 是否有現有的有效憑證。如果沒有,Auth Manager 會傳回授權網址,啟動三方 OAuth (3LO) 同意聲明流程。
  2. 安全保管箱儲存空間:使用者授權應用程式後,Auth Manager 會自動攔截 OAuth 回呼,並將產生的使用者存取權杖和更新權杖,儲存在 Google 代管的安全憑證保管箱。
  3. 自動化權杖生命週期:Auth Manager 會在背景全代管權杖到期和輪替作業,不需手動更新權杖邏輯或停機。
  4. 執行工具時不需密鑰:後續動作中,代理會透過 SPIFFE 代理身分進行驗證,在執行階段動態向驗證管理工具要求使用者的委派存取權杖,讓用戶端和代理程式碼完全不需密鑰。

步驟 A:將 GitHub 設為驗證提供者

執行下列 gcloud 指令,在 Google Cloud 專案中建立 GitHub 驗證提供者。您稍後會提供用戶端 ID 和密鑰:GitHub 必須先知道這個供應商的回呼網址,才會核發這些資訊。

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 重新導向網址:

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)。
    • 首頁網址:輸入前端應用程式的網址 (http://localhost:8501 用於本機原型設計;您可以在正式環境中更新為部署的網址)。
    • 應用程式說明:選填 (可留空)。
    • 授權回呼網址 (重新導向 URI):貼上在步驟 A 擷取的 redirectUrl。
    • 「啟用裝置流程」:不勾選。
  3. 按一下「Register application」。
  4. 在隨即顯示的應用程式頁面,複製「用戶端 ID」,然後按一下「產生新的用戶端密鑰」,並複製產生的「用戶端密鑰」。請儲存這兩個值,在下一個步驟中,您會將這兩個值分別用作 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,但不會傳回 Secret。

👉 完成這個步驟後,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 要求該使用者的權杖。如果尚未取得權杖,ADK 會提示使用者登入,而不是直接失敗。硬式編碼的 GITHUB_TOKEN 已完全消失。

6. 將代理部署至 Agent Runtime

GitHub MCP 工具已更新,可使用 Auth Manager,接下來要將代理部署至 Agent Runtime。部署時啟用代理身分,即可為代理佈建專屬 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"

使用代理身分部署代理

使用 adk deploy agent_engine 部署。這會為代理佈建專屬的代理身分,也就是屬於這項部署作業、由 SPIFFE 支援的專屬加密身分,代理會使用這項身分向 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 用戶端指向該代理。

授權代理身分

現在代理已在雲端執行,需要取得權限,才能存取儲存在 Auth Manager 的憑證。根據預設,代理程式的 SPIFFE 身分無法存取外部雲端資源。

執行下列 gcloud 指令,將 roles/agentidentity.user 角色授予代理在驗證提供者資源的身分。這樣一來,代理程式就能取得從保管箱要求使用者權杖所需的確切權限,不會取得其他權限。

# 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"

👉 您也可以從 Google Cloud 控制台取得已部署代理的完整 --member="principal://..." 值:前往 Agent Runtime 控制台,選取已部署的代理,前往「身分」分頁,然後直接複製完整的 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 同意聲明流程

代理已部署至 Agent Runtime,並具備安全的代理身分,接下來要提供自訂前端介面,讓使用者與代理對話。更重要的是,Google Cloud Auth Manager 需要用戶端應用程式回呼處理常式,才能完成驗證迴圈。

雖然 Google Cloud Auth Manager 會在保管箱中安全管理使用者憑證,但無法自行完成 OAuth 權杖交換。3LO 握手程序仰賴用戶端應用程式來彌補差距:

  1. 使用者授權 GitHub 應用程式後,GitHub 會將他們重新導向回代理身分驗證服務供應商 的 redirectUrl。
  2. 接著,Auth Manager 會將使用者的瀏覽器彈出式視窗重新導向至用戶端回呼網址 (continue_uri)。
  3. 用戶端應用程式必須攔截這項重新導向、從瀏覽器的 Cookie 讀取 Nonce,並呼叫 Google Cloud 的 credentials:finalize 端點來完成握手。
  4. 用戶端完成交換後,Google Cloud 會將權杖安全地儲存在驗證提供者的保管箱中,讓代理呼叫 GitHub 工具。

如果沒有這個自訂用戶端託管回呼端點,就無法完成握手,保管箱也無法儲存憑證。

互動式 OAuth 3LO 流程涵蓋多個層級。以下是工具要求的完整執行生命週期。我們會在下方說明和下一個步驟中詳細介紹。

👉 點選圖片即可放大。

3 Legged OAuth 序列流程

客戶在交接過程中的核心責任

  • 轉發同意聲明驗證 (步驟 5-6):代理會發出 adk_request_credential,其中包含同意聲明網址和單次使用的 Nonce;用戶端會開啟彈出式視窗,並將 Nonce 儲存為 Cookie。
  • 託管重新導向回呼 (步驟 10-11): /validateUserId,驗證管理員會在使用者同意後傳送彈出式視窗。
  • 完成權杖設定 (步驟 12 至 14):將重新導向的驗證狀態與快取的 Nonce 結合,然後呼叫 credentials:finalize,將權杖儲存在保管箱中。

建構自己的用戶端

您不需要為實驗室編寫這個用戶端,下一步會執行預先建構的用戶端。在自己的應用程式中實作這項功能時,可以參考以下兩份文件:

8. 在本機執行 UI 用戶端

如 3LO 同意聲明流程序列圖所示,Auth Manager 會將瀏覽器視窗重新導向至用戶端回呼端點。adk-python 存放區中的範例用戶端會在 /validateUserId 代管該端點。請按照下列步驟下載並在本機執行。

下載用戶端檔案

adk-python 中的 contributing/samples/integrations/gcp_auth/client 目錄包含三個重要資產:

  • main.py:FastAPI 後端,會連線至已部署的 Agent Engine,並託管 /validateUserId 回呼端點,以完成 OAuth 權杖。
  • static/:瀏覽器對話 UI 的 HTML 和 JavaScript 檔案。
  • requirements.txt:執行用戶端伺服器所需的 Python 套件。

由於 adk-python 是大型存放區,請使用 Git 的稀疏檢出功能,只下載 contributing/samples/integrations/gcp_auth/client 資料夾:

  1. 首先,請移至 secure-agent-demo 的上一層目錄,將用戶端複製到同層資料夾:
    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. 開啟瀏覽器分頁,然後前往用戶端網址:http://localhost:8501。
  2. 在左側窗格的「Configuration Settings」下方,將「Agent Type」設為 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:由於代理尚未取得使用者工作階段的憑證,因此會收到驗證查問,並在對話串中顯示「需要驗證」資訊卡。
  1. 系統會開啟另一個瀏覽器彈出式視窗,透過 Google Cloud 的 Auth Manager 將您重新導向至 GitHub OAuth 授權頁面。
  2. 查看要求的權限,然後按一下「授權」。
  3. GitHub 會重新導向回 Google Cloud,後者會將彈出式視窗重新導向至您的 localhost 回呼網址 /validateUserId。
  4. 回呼服務會處理並完成憑證交握。

步驟 C:繼續

  1. 彈出式視窗關閉後,父項即時通訊分頁會自動偵測到關閉。
  2. 前端會將繼續酬載傳回代理。
  3. 代理會從 Google Cloud Auth Manager 安全地擷取新交換的權杖,代表您呼叫 GitHub MCP 工具,並將 GitHub 資料直接串流回對話視窗,這些資料是代理無法自行取得的。

步驟 D:查看 Cloud 記錄檔

如要確認權杖交換和最終處理作業是否安全進行,請按照下列步驟操作:

  1. 前往 Google Cloud 控制台的記錄檔探索工具。
  2. 找出確認 nonce 擷取和驗證成功的伺服器記錄:
    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. 在執行本機 uvicorn 伺服器的終端機中按下 Ctrl+C 鍵,停止伺服器。
  2. 移除在本實驗室建立的專案目錄:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. 恭喜!

您已成功建構及保護代理,可代表已登入的使用者執行動作!

學到的內容:

  • 代理程式系統身分:代理程式如何以自己的帳戶身分運作,安全地與 GCP 基礎架構互動、管理遙測記錄,以及呼叫憑證完成 API。
  • 使用者委派身分:代理如何觸發三方 OAuth (3LO) 同意流程,要求授權在外部平台 (例如 GitHub) 代表使用者執行動作。
  • 安全整合工具:如何使用 Google Cloud Auth Manager,將 ADK 代理連至 Model Context Protocol (MCP) 伺服器,動態擷取使用者權杖,而非使用硬式編碼密鑰。
  • IAM 政策設定:如何設定精細的權限繫結,授權 Agent Runtime 身分和您在驗證服務供應商的帳戶。

延伸閱讀