Google Cloud 工具集成¶

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

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

Google Cloud 工具

Apigee API Hub 工具¶

Supported in ADKPython v0.1.0

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 = APIHubToolset(
    name="apihub-sample-tool",
    description="示例工具",
    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 尝试你的智能体。

应用集成工具¶

Supported in ADKPython v0.1.0Java v0.3.0

使用 ApplicationIntegrationToolset，你可以无缝地让你的智能体通过集成连接器的 100 多个预构建连接器安全且受管理地访问企业应用程序用于 Salesforce、ServiceNow、JIRA、SAP 等系统。

它支持本地和 SaaS 应用程序。此外，你可以通过将应用集成工作流作为工具提供给你的 ADK 智能体，将你现有的应用集成过程自动化转变为智能体工作流。

应用集成中的联合搜索让你可以使用 ADK 智能体同时查询多个企业应用程序和数据源。

在此视频演示中了解应用集成中的 ADK 联合搜索如何工作

先决条件¶

1. 安装 ADK¶

按照安装指南中的步骤安装智能体开发工具包。

2. 安装 CLI¶

安装 Google Cloud CLI。要使用默认凭据运行该工具，请运行以下命令：

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

将 <project-id> 替换为你的 Google Cloud 项目的唯一 ID。

3. 配置应用集成工作流并发布连接工具¶

使用一个现有的应用集成工作流或集成连接器连接你想要与你的智能体一起使用的连接。你也可以创建一个新的应用集成工作流或一个连接。

从模板库中导入并发布连接工具。

注意: 要使用集成连接器中的连接器，你需要在与你的连接相同的区域中配置应用集成。

4. 创建项目结构¶

PythonJava

设置你的项目结构并创建所需文件：

project_root_folder
├── .env
└── my_agent
    ├── __init__.py
    ├── agent.py
    └── tools.py

运行智能体时，请确保从 project_root_folder 运行 adk web。

设置你的项目结构并创建所需文件：

  project_root_folder
  └── my_agent
      ├── agent.java
      └── pom.xml

运行智能体时，请确保从 project_root_folder 运行命令。

5. 设置角色和权限¶

要获得设置 ApplicationIntegrationToolset 所需的权限，你必须在项目上拥有以下 IAM 角色（集成连接器和应用集成工作流通用）：

- roles/integrations.integrationEditor
- roles/connectors.invoker
- roles/secretmanager.secretAccessor

注意： 部署时使用智能体引擎 (AE) 时，不要使用 roles/integrations.integrationInvoker，因为它可能导致 403 错误。请改用 roles/integrations.integrationEditor。

使用集成连接器¶

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

开始之前¶

注意： ExecuteConnection 集成通常在你在给定区域中配置应用集成时自动创建。如果 ExecuteConnection 在集成列表中不存在，你必须按照以下步骤创建它：

要使用集成连接器中的连接器，点击 QUICK SETUP 并在与连接相同的区域中配置应用集成。

Google Cloud Tools

转到模板库中的连接工具模板并点击 USE TEMPLATE。
填写集成名称为 ExecuteConnection（必须只使用此集成名称）并选择与连接区域相同的区域。点击"创建 (CREATE)"。
点击 PUBLISH 在 应用集成 编辑器中发布集成。

步骤：

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

创建应用集成工具集¶

要为集成连接器创建应用集成工具集，请按照以下步骤操作：

在 tools.py 文件中使用 ApplicationIntegrationToolset 创建工具：

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

connector_tool = ApplicationIntegrationToolset(
    project="test-project", # TODO: 替换为连接的 GCP 项目
    location="us-central1", #TODO: 替换为连接的位置
    connection="test-connection", #TODO: 替换为连接名称
    entity_operations={"Entity_One": ["LIST","CREATE"], "Entity_Two": []},#空列表表示支持实体的所有操作
    actions=["action1"], #TODO: 替换为操作
    service_account_json='{...}', # 可选。服务账号密钥的字符串化 json
    tool_name_prefix="tool_prefix2",
    tool_instructions="..."
)

注意：

你可以提供服务账号用于身份验证，而不是使用默认凭据。只需生成服务账号密钥并为服务账号分配正确的应用集成和集成连接器 IAM 角色。
要查找连接器支持的实体和操作列表，请使用连接器 apis: listActions 或 listEntityTypes

ApplicationIntegrationToolset 支持 auth_scheme 和 auth_credential，用于集成连接器的 动态 OAuth2 认证。要使用它，可以在 tools.py 文件中创建一个类似这样的工具：

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: 替换为连接的 GCP 项目
    location="us-central1", #TODO: 替换为连接的位置
    connection="test-connection", #TODO: 替换为连接名称
    entity_operations={"Entity_One": ["LIST","CREATE"], "Entity_Two": []},#空列表表示支持实体的所有操作
    actions=["GET_calendars/%7BcalendarId%7D/events"], #TODO: 替换为操作。这个是列出事件
    service_account_json='{...}', # 可选。服务账号密钥的字符串化 json
    tool_name_prefix="tool_prefix2",
    tool_instructions="...",
    auth_scheme=oauth_scheme,
    auth_credential=auth_credential
)

更新 agent.py 文件并将工具添加到你的智能体：

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],
)

配置 __init__.py 以公开你的智能体：
```
from . import agent
```
启动 Google ADK Web UI 并使用你的智能体：
```
# 确保从你的 project_root_folder 运行 `adk web`
adk web
```
完成上述步骤后，前往 http://localhost:8000，并选择 my_agent 智能体（与智能体文件夹名称相同）。

使用应用集成工作流¶

使用现有的应用集成工作流作为智能体的工具或创建新的工作流。

使用现有的应用集成工作流作为你的智能体的工具或创建一个新的。

1. 创建工具¶

PythonJava

要在 tools.py 文件中使用 ApplicationIntegrationToolset 创建工具，请使用以下代码：

    integration_tool = ApplicationIntegrationToolset(
        project="test-project", # TODO: 替换为连接的 GCP 项目
        location="us-central1", #TODO: 替换为连接的位置
        integration="test-integration", #TODO: 替换为集成名称
        triggers=["api_trigger/test_trigger"],#TODO: 替换为触发器 id(s)。空列表表示考虑集成中的所有 api 触发器。
        service_account_json='{...}', #可选。服务账号密钥的字符串化 json
        tool_name_prefix="tool_prefix1",
        tool_instructions="..."
    )

注意： 你可以提供一个服务账号来代替使用默认凭据。为此，生成一个服务账号密钥并为服务账号提供正确的应用集成和集成连接器 IAM 角色。有关 IAM 角色的更多详细信息，请参阅先决条件部分。

要在 tools.java 文件中使用 ApplicationIntegrationToolset 创建工具，请使用以下代码：

    import com.google.adk.tools.applicationintegrationtoolset.ApplicationIntegrationToolset;
    import com.google.common.collect.ImmutableList;
    import com.google.common.collect.ImmutableMap;

    public class Tools {
        private static ApplicationIntegrationToolset integrationTool;
        private static ApplicationIntegrationToolset connectionsTool;

        static {
            integrationTool = new ApplicationIntegrationToolset(
                    "test-project",
                    "us-central1",
                    "test-integration",
                    ImmutableList.of("api_trigger/test-api"),
                    null,
                    null,
                    null,
                    "{...}",
                    "tool_prefix1",
                    "...");

            connectionsTool = new ApplicationIntegrationToolset(
                    "test-project",
                    "us-central1",
                    null,
                    null,
                    "test-connection",
                    ImmutableMap.of("Issue", ImmutableList.of("GET")),
                    ImmutableList.of("ExecuteCustomQuery"),
                    "{...}",
                    "tool_prefix",
                    "...");
        }
    }

注意： 你可以提供一个服务账号来代替使用默认凭据。为此，生成一个服务账号密钥并为服务账号提供正确的应用集成和集成连接器 IAM 角色。有关 IAM 角色的更多详细信息，请参阅先决条件部分。

2. 将工具添加到你的智能体¶

PythonJava

要更新 agent.py 文件并将工具添加到你的智能体，请使用以下代码：

    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],
    )

要更新 agent.java 文件并将工具添加到你的智能体，请使用以下代码：

```java import com.google.adk.agent.LlmAgent; import com.google.adk.tools.BaseTool; import com.google.common.collect.ImmutableList;

    public class MyAgent {
        public static void main(String[] args) {
            // 假设 Tools 类按上一步定义
            ImmutableList<BaseTool> tools = ImmutableList.<BaseTool>builder()
                    .add(Tools.integrationTool)
                    .add(Tools.connectionsTool)
                    .build();

            // 最后，使用自动生成的工具创建你的智能体。
            LlmAgent rootAgent = LlmAgent.builder()
                    .name("science-teacher")
                    .description("科学教师智能体")
                    .model("gemini-2.0-flash")
                    .instruction(
                            "帮助用户，利用你可以访问的工具。"
                    )
                    .tools(tools)
                    .build();

            // 现在你可以使用 rootAgent 与 LLM 交互
            // 例如，你可以开始与智能体的对话。
        }
    }
```

注意： 要查找连接支持的实体和操作列表，请使用这些连接器 API：listActions, listEntityTypes。

3. 公开你的智能体¶

Python

要配置 __init__.py 以公开你的智能体，请使用以下代码：

    from . import agent

4. 使用你的智能体¶

PythonJava

要启动 Google ADK Web UI 并使用你的智能体，请使用以下命令：

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

完成上述步骤后，前往 http://localhost:8000，并选择 my_agent 智能体（与智能体文件夹名称相同）。

要启动 Google ADK Web UI 并使用你的智能体，请使用以下命令：

    mvn install

    mvn exec:java \
        -Dexec.mainClass="com.google.adk.web.AdkWebServer" \
        -Dexec.args="--adk.agents.source-dir=src/main/java" \
        -Dexec.classpathScope="compile"

完成上述步骤后，前往 http://localhost:8000，并选择 my_agent 智能体（与智能体文件夹名称相同）。