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 import McpToolset

auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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://iamconnectorcredentials.googleapis.com/v1alpha/{connector_name}/credentials:finalize。
    • 凭据成功最终确定后，Web 应用应通过发送 FunctionResponse 来恢复智能体。有关示例实现，请参考示例代码。与本机用户同意流程不同，恢复智能体不需要授权码。
    • 有关更多详细信息，请参考示例处理器实现。
  • 恢复对话：无论同意流程的状态如何（成功或不成功），智能体应用都应恢复智能体以完成对话轮次。ADK 会自动确定同意是否成功完成，如果未完成则引发错误。

参考资料