从 Cloud API Registry 连接 MCP 工具

Supported in ADKPython v1.20.0预览

针对智能体开发工具包 (ADK) 的 Google Cloud API Registry 连接器工具让你可以通过 Google Cloud API Registry 以模型上下文协议 (MCP) 服务器的形式为你的智能体访问各种 Google Cloud 服务。你可以配置此工具将你的智能体连接到你的 Google Cloud 项目，并动态访问为该项目启用的 Cloud 服务。

预览版本

Google Cloud API Registry 功能是预览版本。有关更多信息,请参阅 发布阶段描述。

前置条件

在将 API Registry 与你的智能体一起使用之前，你需要确保以下内容：

• Google Cloud 项目： 配置你的智能体使用现有的 Google Cloud 项目访问 AI 模型。

• API Registry 访问： 你的智能体运行的环境需要 Google Cloud 应用默认凭据 并具有 apiregistry.viewer 角色以列出可用的 MCP 服务器。

• Cloud API: 在你的 Google Cloud 项目中，启用 cloudapiregistry.googleapis.com 和 apihub.googleapis.com Google Cloud API。

• MCP 服务器和工具访问： 确保你在 API Registry 中为你想要使用智能体访问的 Cloud 项目中的 Google Cloud 服务启用 MCP 服务器。你可以在 Cloud 控制台中启用此功能，或使用 gcloud 命令，例如： gcloud beta api-registry mcp enable bigquery.googleapis.com --project={PROJECT_ID}。 智能体使用的凭据必须具有访问 MCP 服务器和工具使用的底层服务的权限。例如，要使用 BigQuery 工具，服务账户需要 BigQuery IAM 角色，如bigquery.dataViewer 和 bigquery.jobUser。有关所需权限的更多信息， 请参阅身份验证和访问。

你可以使用以下 gcloud 命令检查哪些 MCP 服务器已启用 API Registry:

gcloud beta api-registry mcp servers list --project={PROJECT_ID}.

与智能体一起使用

在为智能体配置 API Registry 连接器工具时，你首先初始化 ApiRegistry 类以建立与 Cloud 服务的连接，然后使用 get_toolset() 函数检索在 API Registry 中注册的特定 MCP 服务器的工具集。以下代码示例演示了如何创建一个使用 API Registry 中列出的 MCP 服务器工具的智能体。

此智能体旨在与 BigQuery 交互：

import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.api_registry import ApiRegistry

# 使用你的 Google Cloud 项目 ID 和注册的 MCP 服务器名称进行配置
PROJECT_ID = "your-google-cloud-project-id"
MCP_SERVER_NAME = "projects/your-google-cloud-project-id/locations/global/mcpServers/your-mcp-server-name"

# BigQuery 的示例头部提供程序，需要项目头部。
def header_provider(context):
    return {"x-goog-user-project": PROJECT_ID}

# 初始化 ApiRegistry
api_registry = ApiRegistry(
    api_registry_project_id=PROJECT_ID,
    header_provider=header_provider
)

# 获取特定 MCP 服务器的工具集
registry_tools = api_registry.get_toolset(
    mcp_server_name=MCP_SERVER_NAME,
    # 可选过滤工具：
    #tool_filter=["list_datasets", "run_query"]
)

# 使用工具创建智能体
root_agent = LlmAgent(
    model="gemini-1.5-flash", # 或你首选的模型
    name="bigquery_assistant",
    instruction="""
帮助用户使用可用工具访问他们的 BigQuery 数据。
    """,
    tools=[registry_tools],
)

有关此示例的完整代码，请参阅api_registry_agent示例。有关配置选项的信息，请参阅配置。有关此工具的身份验证信息，请参阅身份验证和访问。

身份验证和访问

将 API Registry 与你的智能体一起使用需要对智能体访问的服务进行身份验证。默认情况下，该工具使用 Google Cloud应用默认凭据进行身份验证。使用此工具时，请确保你的智能体具有以下权限和访问权限：

• API Registry 访问： ApiRegistry 类使用应用默认凭据 (google.auth.default()) 对 Google Cloud API Registry 的请求进行身份验证以列出可用的 MCP 服务器。确保智能体运行的环境具有必要权限的凭据以查看 API Registry 资源，例如 apiregistry.viewer。

• MCP 服务器和工具访问： get_toolset 返回的 McpToolset默认情况下也使用 Google Cloud 应用默认凭据对实际 MCP 服务器端点的调用进行身份验证。使用的凭据必须具有以下两项的必要权限：

  1. 访问 MCP 服务器本身。
  2. 利用工具与之交互的底层服务和资源。

• MCP 工具用户角色： 通过授予 MCP 工具用户角色，允许你的智能体使用的账户通过 API 注册表调用 MCP 工具： gcloud projects add-iam-policy-binding {PROJECT_ID} --member={member} --role="roles/mcp.toolUser"

例如，当使用与 BigQuery 交互的 MCP 服务器工具时，与凭据关联的账户 (例如服务账户) 必须在你的 Google Cloud 项目中被授予适当的 BigQuery IAM 角色，例如 bigquery.dataViewer 或 bigquery.jobUser,以访问数据集和运行查询。在 bigquery MCP 服务器的情况下，需要 "x-goog-user-project": PROJECT_ID 头部才能使用其工具。可以过 ApiRegistry 构造函数中的 header_provider

参数注入用于身份验证或项目上下文的额外头部。

配置

APIRegistry 对象具有以下配置选项：

• api_registry_project_id (str): API Registry 所在的 Google Cloud 项目 ID。
• location (str, 可选): API Registry 资源的位置。默认为 "global"。
• header_provider (Callable, 可选): 一个函数，它接受调用上下文并返回一个字典，包含要与对 MCP 服务器的请求一起发送的额外 HTTP 头部。这通常用于动态身份验证或特定于项目的头部。

get_toolset() 函数具有以下配置选项：

• mcp_server_name (str): 要从中加载工具的已注册 MCP 服务器的完整名称，例如：projects/my-project/locations/global/mcpServers/my-server。

• tool_filter (Union[ToolPredicate, List[str]], 可选): 指定要包含在工具集中的工具。

  • 如果是字符串列表，则仅包含名称在列表中的工具。
  • 如果是 ToolPredicate 函数，则为每个工具调用该函数，仅包含返回 True 的工具。
  • 如果为 None,则包含 MCP 服务器中的所有工具。

• tool_name_prefix (str, 可选): 要添加到生成的工具集中每个工具名称的前缀。

额外资源

• api_registry_agent ADK 代码示例
• Google Cloud API Registry 文档