Google Cloud 工具集成¶

Google Cloud 工具让你的智能体更容易连接到 Google Cloud 的产品和服务。只需几行代码，你就可以用这些工具将智能体连接到：

数百万个自定义 API，这些 API 由开发者托管在 Apigee 中。
数百个面向企业系统（如 Salesforce、Workday 和 SAP）的预构建连接器。
使用应用集成构建的自动化工作流。
使用 MCP Toolbox 连接 数据库，如 Spanner、AlloyDB、Postgres 等。

Google Cloud 工具

Apigee API Hub 工具¶

ApiHubToolset 让你能够通过几行代码将 Apigee API hub 中的任何已文档化的 API 转变为工具。本节将向你展示包括为 API 设置安全连接的身份验证在内的分步说明。

前提条件

安装 ADK
安装 Google Cloud CLI。
拥有已文档化（即 OpenAPI 规范）API 的 Apigee API hub 实例
设置项目结构并创建所需文件

project_root_folder
 |
 `-- my_agent
     |-- .env
     |-- __init__.py
     |-- agent.py
     `__ tool.py

创建 API Hub 工具集¶

注意：本教程包括智能体创建。如果你已经有了智能体，你只需要遵循这些步骤的一个子集。

获取你的访问令牌，以便 APIHubToolset 可以从 API Hub API 获取规范。在终端中运行以下命令
```
gcloud auth print-access-token
# 打印你的访问令牌，如 'ya29....'
```
确保使用的账户具有所需的权限。你可以使用预定义的角色 roles/apihub.viewer 或分配以下权限：
1. apihub.specs.get (必需)
2. apihub.apis.get (可选)
3. apihub.apis.list (可选)
4. apihub.versions.get (可选)
5. apihub.versions.list (可选)
6. apihub.specs.list (可选)
使用 APIHubToolset 创建工具。将以下内容添加到 tools.py

如果你的 API 需要身份验证，你必须为该工具配置身份验证。以下代码示例演示了如何配置 API 密钥。ADK 支持基于令牌的身份验证（API 密钥、Bearer 令牌）、服务账户和 OpenID Connect。我们将很快添加对各种 OAuth2 流程的支持。
```
from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential
from google.adk.tools.apihub_tool.apihub_toolset import APIHubToolset

# 为你的 API 提供身份验证。如果你的 API 不需要身份验证，则不需要。
auth_scheme, auth_credential = token_to_scheme_credential(
    "apikey", "query", "apikey", apikey_credential_str
)

sample_toolset_with_auth = APIHubToolset(
    name="apihub-sample-tool",
    description="Sample Tool",
    access_token="...",  # 复制步骤 1 中生成的访问令牌
    apihub_resource_name="...", # API Hub 资源名称
    auth_scheme=auth_scheme,
    auth_credential=auth_credential,
)
```
对于生产部署，我们建议使用服务账户而不是访问令牌。在上面的代码片段中，使用 service_account_json=service_account_cred_json_str 并提供你的安全账户凭据，而不是令牌。

对于 apihub_resource_name，如果你知道用于 API 的 OpenAPI 规范的特定 ID，请使用 `projects/my-project-id/locations/us-west1/apis/my-api-id/versions/version-id/specs/spec-id`。如果你希望工具集自动从 API 中拉取第一个可用的规范，请使用 `projects/my-project-id/locations/us-west1/apis/my-api-id`

创建你的智能体文件 Agent.py 并将创建的工具添加到你的智能体定义中：

from google.adk.agents.llm_agent import LlmAgent
from .tools import sample_toolset

root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='enterprise_assistant',
    instruction='帮助用户，利用你可以访问的工具',
    tools=sample_toolset.get_tools(),
)

配置你的 __init__.py 以公开你的智能体
```
from . import agent
```

启动 Google ADK Web UI 并尝试你的智能体：

# 确保从你的 project_root_folder 运行 `adk web`
adk web

然后前往 http://localhost:8000 从 Web UI 尝试你的智能体。

应用集成工具¶

With ApplicationIntegrationToolset, you can seamlessly give your agents secure and governed access to enterprise applications using Integration Connectors' 100+ pre-built connectors for systems like Salesforce, ServiceNow, JIRA, SAP, and more.

It supports both on-premise and SaaS applications. In addition, you can turn your existing Application Integration process automations into agentic workflows by providing application integration workflows as tools to your ADK agents.

Prerequisites¶

Install ADK.
Use an existing Application Integration workflow or Integrations Connector connection you want to use with your agent.
To use tool with default credentials, install the Google Cloud CLI and run the following commands:

gcloud config set project <project-id>
gcloud auth application-default login
gcloud auth application-default set-quota-project <project-id>

Set up your project structure and create required files.
```
project_root_folder
|-- .env
`-- my_agent
    |-- __init__.py
    |-- agent.py
    `__ tools.py
```
When running the agent, make sure to run adk web in the project\_root\_folder.
To get the permissions that you need to set up ApplicationIntegrationToolset, you must have the following IAM roles on the project (common to both Integration Connectors and Application Integration Workflows):
roles/integration.editor
roles/connectors.user
roles/secretmanager.secretAccessor

Note: For Agent Engine (AE), don't use roles/integration.invoker, as it can result in 403 errors. Use roles/integration.editor instead.

使用集成连接器¶

使用集成连接器将你的智能体连接到企业应用程序。

Before you begin¶

Note: The ExecuteConnection integration is typically created automatically when you provision Application Integration in a given region. If the ExecuteConnection doesn't exist in the list of integrations, you must follow these steps to create it:

To use a connector from Integration Connectors, click QUICK SETUP and provision Application Integration in the same region as your connection.

Google Cloud Tools

Go to the Connection Tool template in the template library and click USE TEMPLATE.
填写集成名称为 ExecuteConnection（必须只使用此集成名称）并选择与连接区域相同的区域。点击"创建 (CREATE)"。
Enter the Integration Name as ExecuteConnection (it is mandatory to use this exact integration name only). Then, select the region to match your connection region and click CREATE.
Click PUBLISH to publish the integration in the Application Integration editor.

步骤：

![Google Cloud Tools](../assets/publish-integration.png)

Create an Application Integration Toolset¶

To create an Application Integration Toolset for Integration Connectors, follow these steps:

Create a tool with ApplicationIntegrationToolset in the tools.py file:

from google.adk.tools.application_integration_tool.application_integration_toolset import ApplicationIntegrationToolset

connector_tool = ApplicationIntegrationToolset(
    project="test-project", # TODO: replace with GCP project of the connection
    location="us-central1", #TODO: replace with location of the connection
    connection="test-connection", #TODO: replace with connection name
    entity_operations={"Entity_One": ["LIST","CREATE"], "Entity_Two": []},#empty list for actions means all operations on the entity are supported.
    actions=["action1"], #TODO: replace with actions
    service_account_json='{...}', # optional. Stringified json for service account key
    tool_name_prefix="tool_prefix2",
    tool_instructions="..."
)

注意：

你可以提供服务账号用于身份验证，而不是使用默认凭据。只需生成服务账号密钥并为服务账号分配正确的 Application Integration 和 Integration Connector IAM 角色。
要查找连接器支持的实体和操作列表，请使用 connectors apis: listActions 或 listEntityTypes
You can provide a service account to be used instead of default credentials by generating a Service Account Key, and providing the right Application Integration and Integration Connector IAM roles to the service account.
To find the list of supported entities and actions for a connection, use the Connectors APIs: listActions or listEntityTypes.

ApplicationIntegrationToolset also supports auth_scheme and auth_credential for dynamic OAuth2 authentication for Integration Connectors. To use it, create a tool similar to this in the tools.py file:

from google.adk.tools.application_integration_tool.application_integration_toolset import ApplicationIntegrationToolset
from google.adk.tools.openapi_tool.auth.auth_helpers import dict_to_auth_scheme
from google.adk.auth import AuthCredential
from google.adk.auth import AuthCredentialTypes
from google.adk.auth import OAuth2Auth

oauth2_data_google_cloud = {
  "type": "oauth2",
  "flows": {
      "authorizationCode": {
          "authorizationUrl": "https://accounts.google.com/o/oauth2/auth",
          "tokenUrl": "https://oauth2.googleapis.com/token",
          "scopes": {
              "https://www.googleapis.com/auth/cloud-platform": (
                  "查看和管理你在 Google Cloud Platform 服务中的数据"
              ),
              "https://www.googleapis.com/auth/calendar.readonly": "查看你的日历"
          },
      }
  },
}

oauth_scheme = dict_to_auth_scheme(oauth2_data_google_cloud)

auth_credential = AuthCredential(
  auth_type=AuthCredentialTypes.OAUTH2,
  oauth2=OAuth2Auth(
      client_id="...", # TODO: 替换为 client_id
      client_secret="...", # TODO: 替换为 client_secret
  ),
)

connector_tool = ApplicationIntegrationToolset(
    project="test-project", # TODO: replace with GCP project of the connection
    location="us-central1", #TODO: replace with location of the connection
    connection="test-connection", #TODO: replace with connection name
    entity_operations={"Entity_One": ["LIST","CREATE"], "Entity_Two": []},#empty list for actions means all operations on the entity are supported.
    actions=["GET_calendars/%7BcalendarId%7D/events"], #TODO: replace with actions. this one is for list events
    service_account_json='{...}', # optional. Stringified json for service account key
    tool_name_prefix="tool_prefix2",
    tool_instructions="...",
    auth_scheme=oauth_scheme,
    auth_credential=auth_credential
)

Update the agent.py file and add tool to your agent:

from google.adk.agents.llm_agent import LlmAgent
from .tools import connector_tool

root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='connector_agent',
    instruction="帮助用户，利用你可以访问的工具",
    tools=[connector_tool],
)

Configure __init__.py to expose your agent:
```
from . import agent
```

Start the Google ADK Web UI and use your agent:

# 确保从你的 project_root_folder 运行 `adk web`
adk web

After completing the above steps, go to http://localhost:8000, and choose my\_agent agent (which is the same as the agent folder name).

使用应用集成工作流¶

Use an existing Application Integration workflow as a tool for your agent or create a new one.

Create an Application Integration Workflow Toolset¶

To create an Application Integration Toolset for Application Integration Workflows, follow these steps:

Create a tool with ApplicationIntegrationToolset in the tools.py file:

integration_tool = ApplicationIntegrationToolset(
    project="test-project", # TODO: replace with GCP project of the connection
    location="us-central1", #TODO: replace with location of the connection
    integration="test-integration", #TODO: replace with integration name
    triggers=["api_trigger/test_trigger"],#TODO: replace with trigger id(s). Empty list would mean all api triggers in the integration to be considered.
    service_account_json='{...}', #optional. Stringified json for service account key
    tool_name_prefix="tool_prefix1",
    tool_instructions="..."
)

Note: You can provide service account to be used instead of using default credentials by generating Service Account Key and providing right Application Integration and Integration Connector IAM roles to the service account. For more details about the IAM roles, refer to the Prerequisites section.

Update the agent.py file and add tool to your agent:

from google.adk.agents.llm_agent import LlmAgent
from .tools import integration_tool, connector_tool

root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='integration_agent',
    instruction="帮助用户，利用你可以访问的工具",
    tools=[integration_tool],
)

Configure `__init__.py` to expose your agent:
```
from . import agent
```

Start the Google ADK Web UI and use your agent:

# 确保从你的 project_root_folder 运行 `adk web`
adk web

After completing the above steps, go to http://localhost:8000, and choose my\_agent agent (which is the same as the agent folder name).

用于数据库的工具箱工具¶

面向数据库的 MCP 工具箱是一个开源 MCP 服务器，用于数据库。它的设计考虑了企业级和生产级质量。通过处理连接池、身份验证等复杂性，它使你能够更轻松、更快速、更安全地开发工具。

Google 的 Agent Development Kit (ADK) 内置了对工具箱的支持。有关入门或配置工具箱的更多信息，请参阅文档。

GenAI 工具箱

配置和部署¶

工具箱是你自己部署和管理的开源服务器。有关部署和配置的更多说明，请参阅官方工具箱文档：

安装客户端 SDK¶

ADK 依赖 toolbox-langchain python 包来使用工具箱。在开始之前安装该包：

pip install toolbox-core

加载工具箱工具¶

一旦你的工具箱服务器配置完成并运行，你可以使用 ADK 从服务器加载工具：

from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient

toolbox = ToolboxSyncClient("https://127.0.0.1:5000")

# 加载特定的工具集
tools = toolbox.load_toolset('my-toolset-name'),
# 加载单个工具
tools = toolbox.load_tool('my-tool-name'),

root_agent = Agent(
    ...,
    tools=tools # 向智能体提供工具列表

)

高级工具箱功能¶

工具箱具有各种功能，可以更轻松地开发用于数据库的生成式 AI 工具。有关更多信息，请阅读以下功能的详细说明：

认证参数：自动将工具输入绑定到 OIDC 令牌中的值，使运行敏感查询变得简单，而不会潜在泄露数据
授权调用：根据用户的 Auth 令牌限制使用工具的访问权限
OpenTelemetry：通过 OpenTelemetry 从工具箱获取指标和跟踪