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

1. 簡介

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

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

具體來說，您會瞭解如何設計雙重身分架構，其中：

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

雙重身分識別架構

為達成此目標，您將瞭解如何：

  1. 建構可連至 GitHub Model Context Protocol (MCP) 伺服器的 ADK 代理。
  2. 使用 Google Cloud Auth Manager，將代理程式的工具從靜態 GitHub PAT (個人存取權杖) 更新為 3 足式 OAuth (3LO) 流程。
  3. 將代理安全地部署至 Agent Runtime，並佈建 Agent Identity。
  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 帳戶，可以改用支援三向 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

這項指令可能需要一分鐘才能執行完畢。完成後，系統會返回命令提示字元，確認 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 ships google-adk[gcp,otel-gcp] 缺少這個代理程式需要的兩個額外項目：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",
)

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

  • 系統指令 (INSTRUCTION)：設定角色、將助理範圍限定為 GitHub 分類，並強制執行嚴格的安全規則 (例如唯讀存取權，以及在發生錯誤時引導使用者驗證)。
  • 代理程式設定 (root_agent)：使用 � model 例項化 ADK Agent、設定 HTTP 重試邏輯，並為代理程式配備 GitHub 工具集。gemini-3.8-flash
  • 應用程式包裝函式 (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 閘道。
  • 授權標頭：以 Bearer 權杖的形式插入 GITHUB_TOKEN，並直接在傳輸層強制執行唯讀模式 (X-MCP-Readonly: true)。

3. 使用 GitHub PAT (個人存取權杖) 在本機進行測試

如要使用靜態憑證在本機執行代理程式，請按照下列步驟操作：

  1. 建立 GitHub 個人存取權杖。授予存放區的讀取權，否則代理程式只能查看公開資料，且以下提示不會傳回任何內容。
  2. 在環境中設定：
    export GITHUB_TOKEN="your_github_pat_here"
  3. 前往 secure-agent-demo 資料夾。執行：
    cd secure-agent-demo
agents-cli playground
  4. 開啟 Playground 介面，然後從下拉式選單選取「app」資料夾。在對話方塊中輸入 "Fetch my contributions across my private repositories over the last 6 months"，確認代理程式呼叫 GitHub 工具，並從私人存放區傳回資料。

4. 設定驗證管理員

雖然將靜態憑證 (例如 PAT) 硬式編碼，方便進行原型設計，但會導致正式版應用程式暴露於憑證外洩風險、手動權杖重新整理停機時間，以及缺乏雲端原生存取控制項。

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

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

驗證管理員工作流程

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

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

執行下列 gcloud 指令，在 Google Cloud 雲端專案中建立 GitHub 驗證供應商。您稍後會提供用戶端 ID 和密鑰：GitHub 必須知道這個供應商的回呼網址，才會核發這些 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 重新導向網址：

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

這個欄位是 authProviderTypeParams.threeLeggedOauth 底下的巢狀欄位 redirectUrl。如要直接閱讀：

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 應用程式

  1. 前往 GitHub 開發人員設定頁面，然後按一下「Register a new OAuth app」。
  2. 在「首頁網址」部分，輸入前端應用程式的網址 (例如 http://localhost:8501，用於本機原型設計。之後可以將其變更為正式環境中部署的網址。
  3. 將「重新導向 URI」設為上一個步驟中擷取的 redirectUrl。
  4. 按一下「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 應用程式憑證，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 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 部署。這會為代理程式提供專屬的Agent Identity，也就是屬於這個部署作業的專屬 SPIFFE 支援加密身分，代理程式會使用這個身分向 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 身分無法存取外部雲端資源。

執行下列 gcloud 指令，在驗證提供者資源上，將 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 Runtime，並具備安全的 Agent Identity，接下來的步驟是提供自訂前端介面，供使用者與代理對話。更重要的是，Google Cloud Auth Manager 需要用戶端應用程式回呼處理常式，才能完成驗證迴圈。

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

  1. 使用者授權 GitHub 應用程式後，GitHub 會將他們重新導向至 Agent Identity 驗證供應商的 redirectUrl。
  2. 然後，Auth Manager 會將使用者的瀏覽器彈出式視窗重新導向至用戶端回呼網址 (continue_uri)。
  3. 用戶端應用程式有責任攔截這項重新導向，從瀏覽器的 Cookie 讀取隨機碼，並呼叫 Google Cloud 的 credentials:finalize 端點來完成信號交換。
  4. 用戶完成交換程序後，Google Cloud 會將權杖安全地儲存在驗證提供者的保管庫中，讓代理程式可以呼叫 GitHub 工具。

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

互動式 OAuth 3LO 流程涵蓋多個層面。以下是工具請求的完整執行生命週期。我們會在下方的說明和下一個步驟中，詳細說明這項功能。

👉 點選圖片即可放大。

3 Legged OAuth 序列流程

合約中客戶的核心責任

  • 轉送同意聲明驗證問題 (步驟 5-6)：代理會發出 adk_request_credential，其中包含同意聲明網址和一次性隨機值；用戶端會開啟彈出式視窗，並將隨機值儲存為 Cookie。
  • 代管重新導向回呼 (步驟 10-11)： /validateUserId，其中 Auth Manager 會在同意聲明後傳送彈出式視窗。
  • 完成權杖 (步驟 12 至 14)：將重新導向的驗證狀態與快取隨機值合併，然後呼叫 credentials:finalize，將權杖儲存在保管庫中。

自行建構用戶端

您不需要為實驗室編寫這個用戶端，下一個步驟會執行預先建構的用戶端。在自己的應用程式中實作這項功能時，請參考下列兩項內容：

8. 在本機執行 UI 用戶端

如 3LO 同意聲明流程順序圖所示，Auth Manager 必須將瀏覽器彈出式視窗重新導向至用戶端回呼端點。範例用戶端會在 /validateUserId 託管該端點。我們在本機執行。

將用戶端檔案複製到本機

前往 adk-python GitHub 存放區中的 gcp_auth/client 資料夾。這個資料夾包含建構即時通訊用戶端容器所需的資產。

👉 將 gcp_auth/client 下的所有檔案複製到本機環境：

  • main.py：FastAPI 應用程式指令碼，其中包含我們在上一節討論的權杖最終化回呼 (/validateUserId)。
  • 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

執行用戶端

  1. 前往剛複製的 client 資料夾：
    cd adk-python/contributing/samples/integrations/gcp_auth/client
  2. 建立虛擬環境並安裝用戶端的依附元件。資料夾會出貨 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
  3. 將用戶端指向您部署的代理程式，然後在連接埠 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
  4. 確認伺服器已順利啟動，並正在接聽 http://localhost:8501。

9. 測試 OAuth 流程

所有服務都已部署、IAM 繫結已設定，且環境變數也已設定完成，現在可以測試安全的端對端使用者委派授權流程！

步驟 A：啟動工具執行作業

  1. 開啟瀏覽器分頁，然後前往用戶端網址：http://localhost:8501。
  2. 在左側窗格中，將代理程式類型設為 Remote Agent Engine。
  3. 輸入 Google Cloud 專案和位置。按一下 Load Remote Agents。這時應該會載入部署至專案的所有代理程式。
  4. 從下拉式選單中選取正確的代理程式，然後儲存設定。
  5. 在對話方塊中輸入：
    Fetch my contributions across my private repositories over the last 6 months
    然後按下 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 工具，並直接將私人存放區的資料串流回聊天視窗，這些資料是代理程式無法自行存取的。

步驟 D：檢查 Cloud 記錄檔

如要確認權杖交換和最終程序是否安全無虞，請採取下列做法：

  1. 前往 Google Cloud 控制台的「Logs Explorer」(記錄檔探索工具)。
  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. 在執行本機 uvicorn 伺服器的終端機中按下 Ctrl+C，停止伺服器。
  2. 移除在本實驗室中建立的專案目錄：
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. 恭喜！

您已成功建構並保護代理，代表登入的使用者執行動作！

學到的內容：

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

延伸閱讀