Skip to content

ADK 的智能体身份认证管理工具

Supported in ADKPython v1.30.0Preview

Google Cloud 智能体身份服务提供了一种经过简化的、由 Google 管理的解决方案，用于管理身份验证凭据的完整生命周期，包括存储凭据配置、生成和存储令牌以及审计访问。这种方法可带来安全且简化的智能体开发体验。

预览版

智能体身份认证管理工具功能是一个预览版。有关更多 信息，请参见发布阶段 说明。

使用场景

  • 简化的 OAuth 流程：无需构建自定义基础设施即可管理身份验证凭据的完整生命周期。
  • 安全的令牌交换和存储：安全地存储凭据配置并交换令牌。
  • 审计日志记录：查看和审计对存储凭据的访问。

前置条件

安装

安装 agent-identity 额外包组以下载必要的客户端库。

pip install "google-adk[agent-identity]"

在智能体中使用

请按照以下步骤在 ADK 中使用智能体身份认证管理工具：

注册身份验证提供方

要使 ADK 能够确定对指定 CustomAuthScheme 使用哪个 BaseAuthProvider，请向 CredentialManager 注册 GcpAuthProvider 实例。这只需要在智能体代码中执行一次。

from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

CredentialManager.register_auth_provider(GcpAuthProvider())

配置工具

使用 GcpAuthProviderScheme 对象配置智能体身份认证提供方，然后将其传递给任何受支持的 Tool 或 Toolset 的 auth_scheme 参数。以下示例展示了与 McpToolset 的用法，但 GcpAuthProviderScheme 也适用于其他工具，如 AuthenticatedFunctionTool。请参阅 GCP Auth 示例 以获取完整示例。

from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool import StreamableHTTPConnectionParams

auth_scheme = GcpAuthProviderScheme(
    # 如果使用旧版 V1 API，资源名称使用 'connectors'
    # 而不是 'authProviders': projects/.../connectors/...
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
    # continue_uri 仅在三方 OAuth 流程中需要。此 URI 接收
    # 用户授权后的重定向，必须由你的应用托管。
    continue_uri=CONTINUE_URI
)

toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)
  • 检测身份验证请求：与现有流程类似，当需要用户 授权时，会生成一个名为 adk-request-credential 的 FunctionCall 事件，其中包含 auth_uri 字段。用户应用应在弹出窗口中打开 auth_uri 以继续用户授权流程。
  • 继续 URI 处理器：
    • 当用户在第三方 提供方的网站上完成 OAuth 授权流程后，系统会重定向到 GcpAuthProviderScheme 中之前定义的 continue_uri 回调。智能体 应用服务必须实现此重定向。要完成凭据签发， 你的处理器必须向凭据端点提交 POST 请求： https://agentidentitycredentials.googleapis.com/v1/{auth_provider_name}/credentials:finalize。
    • 凭据成功签发后，Web 应用应通过发送 FunctionResponse 来 恢复智能体。有关示例 实现，请参阅示例代码。 与原生用户授权流程不同，恢复智能体不需要授权码。
    • 有关更多详情，请参阅示例处理器 实现。
  • 恢复对话：无论授权流程的状态如何 （成功或失败），智能体应用都应恢复智能体以 完成对话轮次。ADK 会自动判断授权是否 成功完成，如果未成功则会抛出错误。

参考资料