ADK 的 Google Cloud Application Integration 工具¶

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

![Google Cloud Tools](../assets/use-connection-tool-template.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 文件并将工具添加到你的智能体，请使用以下代码：

    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 智能体（与智能体文件夹名称相同）。