使用 Agent Identity 和 Auth Manager 构建可代表用户执行操作的 AI 智能体

1. 简介

拥有自己的凭据且权限广泛的代理可以查看所有人的数据。在此 Codelab 中，您将构建一个智能体，该智能体使用已登录用户的自有凭据调用第三方 API，因此它只能看到该用户可以看到的内容，而无法看到其他内容。

您将使用 Google 智能体开发套件 (ADK) 和 Gemini Enterprise 构建该智能体。

具体来说，您将学习如何设计双身份架构，其中：

1. 代理代表自己行事（Agent Identity）：代理使用 SPIFFE 支持的 Agent Identity 来调用 Auth Manager、存储遥测数据和调用 Google Cloud API。
2. 代理代表用户行事（用户委托的身份）：为了访问 GitHub 等外部资源，代理会触发三方 OAuth (3LO) 同意流程，以使用用户凭据安全地查询工具。

为此，您将学习如何：

1. 构建一个连接到 GitHub 的 Model Context Protocol (MCP) 服务器的 ADK 代理。
2. 使用 Google Cloud Auth Manager 将代理的工具从静态 GitHub PAT（个人访问令牌）更新为 3-legged OAuth (3LO) 流程。
3. 将代理安全地部署到 Agent Runtime 并预配 Agent Identity。
4. 配置 IAM 角色，以代表用户向令牌保险库提供代理的身份访问权限。
5. 了解 Google Cloud 中身份验证管理器的端到端 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 账号，可以改用支持三足式 OAuth 2.0 的任何第三方 MCP 服务器。

2. 项目设置

1. 向 Google Cloud 进行身份验证

从本地命令行向 Google Cloud 进行身份验证，以确保您的环境在本实验期间拥有部署到 Agent Runtime、预配 Agent Identity 和配置身份验证管理器所需的权限：

运行以下命令以登录您的 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. 安装代理 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] 缺少此代理所需的两个额外功能：GitHub 工具集的 mcp 和实验后期使用的身份验证管理器的 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)：使用 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 网关。
• 授权标头：将 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. 配置 Auth Manager

虽然对静态凭据（例如 PAT）进行硬编码便于进行原型设计，但会导致正式版应用面临凭据泄露、手动令牌刷新停机时间和缺少云原生访问权限控制的风险。

为了解决这一问题，Google Cloud 提供了Agent Identity 身份验证管理器。Agent Identity Auth Manager 是一种凭据保险库，旨在帮助保护凭据。它允许客服人员使用 API 密钥或 OAuth 客户端 ID 和密钥进行身份验证，也可以通过 OAuth 委托使用最终用户访问令牌代表用户进行身份验证。

在身份验证管理器中，您可以配置身份验证提供方，以定义特定第三方应用的身份验证类型和凭据。身份验证提供程序是区域性的，其区域必须与您部署代理的区域相匹配。端到端身份验证管理器工作流程的运作方式如下：

1. 动态同意拦截：当代理尝试代表用户执行工具时，ADK 会检查身份验证管理器中是否存在有效的现有凭据。如果不存在，身份验证管理器会返回一个授权网址，以启动三方 OAuth (3LO) 意见征求流程。
2. 保险柜安全存储：最终用户授权应用后，身份验证管理器会自动拦截 OAuth 回调，并将生成的用户访问令牌和刷新令牌存储在由 Google 管理的安全凭据保险柜中。
3. 自动令牌生命周期：身份验证管理器可在后台完全管理令牌过期和轮换，无需手动刷新令牌逻辑或停机。
4. 无密钥工具执行：对于后续操作，代理（通过其 SPIFFE Agent Identity 进行身份验证）会在运行时从身份验证管理器动态请求用户的委托访问令牌，从而使客户端和代理代码完全不含密钥。

重要提示：在此 Codelab 中，您会看到大写的占位变量（例如 YOUR_PROJECT_ID、YOUR_PROJECT_NUMBER、YOUR_ORG_ID 和 YOUR_ENGINE_ID）。请务必在运行命令时将这些变量替换为您自己的 Google Cloud 云项目和资源值。

步骤 A：将 GitHub 配置为身份验证提供方

运行以下 gcloud 命令，在您的 Google Cloud 云项目中创建 GitHub 身份验证提供方。您稍后会提供客户端 ID 和密钥：GitHub 在知道此提供方的回调网址之前不会发放它们。

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"

该字段为 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 应用

1. 前往 GitHub 开发者设置页面，然后点击注册新的 OAuth 应用。
2. 对于主页网址，请输入前端应用的网址（例如，http://localhost:8501 用于本地原型设计。您稍后可以在生产环境中将其更改为已部署的网址。
3. 将重定向 URI 设置为上一步中检索到的 redirectUrl。
4. 点击注册应用，然后点击生成新的客户端密钥，并保存客户端 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 可见；不会回显 Secret。

👉 完成此步骤后，您的 Google Cloud Auth Manager 现已完全配置为使用 GitHub OAuth 应用凭据，从而将 Google Cloud 设置为安全保险库，用于处理同意情况和令牌生命周期。

5. 将 PAT 令牌切换到身份验证管理器

现在，身份验证管理器已完全配置，下一步是更新代理的工具代码。将 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 会先向身份验证管理器请求该用户的令牌；如果还没有令牌，它会提示用户登录，而不是失败。硬编码的 GITHUB_TOKEN 已完全移除。

6. 将代理部署到 Agent Runtime

现在，我们已更新 GitHub MCP 工具以使用身份验证管理器，下一步是将代理部署到 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 进行部署。这会为代理配置其自己的Agent Identity，即属于此部署的唯一 SPIFFE 支持的加密身份，代理使用该身份向身份验证管理器和其他 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 值，因为您需要使用它来授权代理，并让界面客户端指向它。

使用 adk deploy agent_engine，而不是 agents-cli deploy --agent-identity。两者都成功部署，但会生成不同的资源形状。agents-cli deploy 构建了一个没有 classMethods 的容器服务器；您稍后运行的界面客户端会调用已部署的代理上的 create_session()，并因 'AgentEngine' object has no attribute 'create_session' 而失败。adk deploy agent_engine 会生成序列化后的 AdkApp 形，其中公开了客户端所需的 13 种方法。

用户同意后到达的页面：用户批准访问权限后，其浏览器会被发送到 OAUTH_CONTINUE_URI 中的地址，该地址由您自己的客户端应用提供。在本实验中，客户端在您的机器上运行，因此代理会使用 app/tools.py (http://localhost:8501/validateUserId) 中已设置的默认值，您无需进行任何更改。如果您稍后在其他位置托管客户端，请在部署之前更新该默认值。

授权 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"

现在，向提供方授予您自己的账号相同的角色。您在下一步中运行的界面客户端会使用应用默认凭据调用凭据最终确定 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 会将用户重定向回 Agent Identity 身份验证提供程序的 redirectUrl。
2. 然后，身份验证管理器会将用户浏览器的弹出式窗口重定向回客户端回调网址 (continue_uri)。
3. 客户端应用负责拦截此重定向，从浏览器的 Cookie 中读取随机数，并调用 Google Cloud 的 credentials:finalize 端点来完成握手。
4. 当客户端完成交换后，Google Cloud 会将令牌安全地保存在身份验证提供方的保险库中，从而允许代理调用 GitHub 工具。

如果没有此托管回调端点的自定义客户端，握手将保持不完整状态，并且保险柜无法存储凭据。

交互式 OAuth 3LO 流程跨越多个层。以下是工具请求的完整执行生命周期。我们将在下方的说明和下一步中详细介绍这一点。

👉 点击图片可放大。

握手阶段客户的核心责任

• 中继同意质询（步骤 5-6）：代理会发出一个携带同意 URL 和一次性随机数的 adk_request_credential；客户端会打开弹出式窗口并将随机数存储为 Cookie。
• 托管重定向回调（步骤 10-11）： /validateUserId，授权管理器会在用户同意后发送弹出式窗口。
• 最终确定令牌（步骤 12-14）：将重定向中的验证状态与缓存的随机数相结合，然后调用 credentials:finalize，该函数会将令牌存储在保险库中。

构建自己的客户端

您无需为本实验编写此客户端，下一步会运行预构建的客户端。当您在自己的应用中实现此功能时，可以参考以下两项内容：

• 更新客户端应用（在身份验证管理器文档中），其中涵盖了处理同意质询和调用 credentials:finalize。
• adk-python 代码库中的可运行示例客户端。请参阅 main.py，了解上述三项职责的完整实现。

8. 在本地运行界面客户端

正如我们在 3LO 许可流程序列图中跟踪到的那样，身份验证管理器需要将浏览器弹出式窗口重定向回客户端回调端点。示例客户端在 /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

运行客户端

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。

使用 localhost，而不是 127.0.0.1。OAuth 重定向需要 localhost 主机名；即使两者解析为同一地址，在此处也不能互换。

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. 观察聊天界面：由于代理尚未获得用户会话的凭据，因此会收到身份验证质询，并在对话串中显示“需要进行身份验证”卡片。

步骤 B：完成三方模式 OAuth 权限请求

1. 系统会打开一个单独的浏览器弹出式窗口，通过 Google Cloud 的身份验证管理器将您重定向到 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 控制台中的日志浏览器。
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 概览
• ADK 文档
• Model Context Protocol