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

1. 简介

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

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

具体来说,您将学习如何设计双重身份架构,其中:

  1. 智能体代表自身执行操作(智能体身份):智能体使用 SPIFFE 支持的智能体身份,调用 Auth Manager、存储遥测数据并调用 Google Cloud API。
  2. 智能体代表用户执行操作(用户委托身份):为了访问 GitHub 等外部资源,智能体触发三方 OAuth (3LO) 同意流程,使用用户的凭据安全地查询工具。

双重身份架构

为此,您将学习如何:

  1. 构建一个连接到 GitHub 的 Model Context Protocol (MCP) 服务器的 ADK 智能体。
  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 账号,可以替换为任何支持三足式 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 服务

在 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 中添加两个缺失的 extra:mcp(用于 GitHub 工具集)和 agent-identity(用于稍后在实验中使用的 Auth Manager)。打开 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(所有代码库),或选择要用于测试的特定代码库。
    • 在权限 > 代码库下,点击 +添加权限,然后选择内容、问题和拉取请求,并将其设置为只读(元数据会自动设置为只读)。
    • 点击生成令牌,然后复制生成的令牌值。(或者,如果您使用个人访问令牌 [经典],请选择 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. 配置 Auth Manager

虽然对静态凭证(例如 PAT)进行硬编码便于原型设计,但它会使生产应用面临凭证泄露、手动令牌刷新停机以及缺乏云原生访问权限控制等风险。

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

在 Auth Manager 中,您可以配置身份验证提供方,为特定第三方应用定义身份验证类型和凭证。身份验证提供方是区域性的,且区域必须与您部署智能体的区域一致。端到端 Auth Manager 工作流的运作方式如下:

Auth 管理员工作流

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

步骤 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(OAuth 应用),然后点击 New OAuth App(新建 OAuth 应用)(如果您之前未创建过应用,请点击 Register a new application [注册新应用])。
  2. 填写 OAuth 应用表单字段:
    • 应用名称:输入应用的名称(例如 secure-agent-demo)。
    • 首页网址:输入前端应用的网址(对于本地原型设计,输入 http://localhost:8501;在生产环境中,您可以将其更新为已部署的网址)。
    • 应用说明:可选(您可以留空)。
    • Authorization callback URL(授权回调网址,即重定向 URI):粘贴在第 A 步中检索到的 redirectUrl。
    • 启用设备流程:不选中。
  3. 点击注册应用。
  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 可见;密钥不会回显。

👉 完成此步骤后,您的 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 值,因为您需要用它来授权智能体,并让界面客户端指向它。

为代理身份授权

现在,您的代理已在云端运行,它需要获得访问 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://... 字符串。

现在,为您自己的账号授予提供商的相同角色。您在下一步中运行的界面客户端会使用您的应用默认凭证调用凭证最终确定 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,用户同意后,Auth Manager 会将弹出式窗口发送到该回调。
  • 最终确定令牌(第 12-14 步):将重定向中的验证状态与缓存的 Nonce 结合,然后调用 credentials:finalize,将令牌存储在保险柜中。

构建您自己的客户端

您无需为此实验编写此客户端,下一步将运行一个预构建的客户端。在您自己的应用中实现此功能时,可以参考以下两个文档:

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

如 3LO 同意流程序列图所示,Auth Manager 会将浏览器窗口重定向回客户端回调端点。adk-python 代码库中的示例客户端在 /validateUserId 托管该端点。请按照以下步骤下载并在本地运行该脚本。

下载客户端文件

adk-python 中的 contributing/samples/integrations/gcp_auth/client 目录包含三个关键资源:

  • main.py:FastAPI 后端,用于连接到已部署的 Agent Engine,并托管 /validateUserId 回调端点以最终确定 OAuth 令牌。
  • static/:浏览器聊天界面的 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. 在左侧窗格中的配置设置下,将代理类型设置为 Remote Agent (Vertex AI)(或 Remote Agent Engine)。
  3. 输入您的 Google Cloud 项目 ID 和位置 (us-central1),然后点击加载远程代理。这会加载部署到您项目中的智能体。
  4. 从选择引擎下拉菜单中选择已部署的 app 代理,然后点击保存并应用设置。
  5. 在对话框中,输入一个有针对性的查询(例如获取您最近的问题或代码库):
    Get the last 2 GitHub issues reported against my name
    
    (或尝试 "List my 3 most recently updated repositories"),然后按 Enter 键。
  6. 观察对话界面:由于代理尚无用户会话的凭据,因此会收到身份验证质询,并在对话串中显示“需要身份验证”卡片。
  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 Logging 日志

如需验证令牌交换和最终确定是否已安全处理,请执行以下操作:

  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 身份和您自己的账号授权。

延伸阅读