Application Integration Tools for ADK¶

ADK 的应用集成工具¶

Supported in ADKPython v0.1.0Java v0.3.0

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.

使用 ApplicationIntegrationToolset,你可以为智能体提供安全且受控的企业应用程序访问,利用 Integration Connectors 提供的 100+ 个预构建连接器,这些连接器适用于 Salesforce、ServiceNow、JIRA、SAP 等系统。

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.

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

Federated search within Application Integration lets you use ADK agents to query multiple enterprise applications and data sources simultaneously.

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

See how ADK Federated Search in Application Integration works in this video walkthrough

在此视频演练中查看 Application Integration 中的 ADK 联合搜索如何工作

Prerequisites¶

前提条件¶

1. Install ADK¶

1. 安装 ADK¶

Install Agent Development Kit following the steps in the installation guide.

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

2. Install CLI¶

2. 安装 CLI¶

Install the Google Cloud CLI. To use the tool with default credentials, run the following commands:

安装 Google Cloud CLI。要使用默认凭据的工具,请运行以下命令:

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

Replace <project-id> with the unique ID of your Google Cloud project.

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

3. Provision Application Integration workflow and publish Connection Tool¶

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

Use an existing Application Integration workflow or Integrations Connector connection you want to use with your agent. You can also create a new Application Integration workflow or a connection.

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

Import and publish the Connection Tool from the template library.

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

Note: To use a connector from Integration Connectors, you need to provision the Application Integration in the same region as your connection.

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

4. Create project structure¶

4. 创建项目结构¶

PythonJava

Set up your project structure and create the required files:

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

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

When running the agent, make sure to run adk web from the project_root_folder.

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

Set up your project structure and create the required files:

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

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

When running the agent, make sure to run the commands from the project_root_folder.

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

5. Set roles and permissions¶

5. 设置角色和权限¶

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):

要获得设置 ApplicationIntegrationToolset 所需的权限,你必须在项目上拥有以下 IAM 角色(对于 Integration Connectors 和应用程序集成工作流都是通用的):

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

Note: When using Agent Engine (AE) for deployment, don't use roles/integrations.integrationInvoker, as it can result in 403 errors. Use roles/integrations.integrationEditor instead.

注意: 使用智能体引擎(AE)进行部署时,不要使用 roles/integrations.integrationInvoker,因为这可能会导致 403 错误。请改用 roles/integrations.integrationEditor。

Use Integration Connectors¶

使用集成连接器¶

Connect your agent to enterprise applications using Integration Connectors.

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

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:

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

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

要使用 Integration Connectors 中的连接器,请单击 QUICK SETUP 并在与连接相同的区域配置应用程序集成。

Google Cloud Tools

Go to the Connection Tool template in the template library and click USE TEMPLATE.

转到模板库中的连接工具模板,然后单击 USE TEMPLATE。
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.

输入集成名称为 ExecuteConnection(必须仅使用此确切的集成名称)。然后,选择与连接区域匹配的区域,然后单击 CREATE。
Click PUBLISH to publish the integration in the Application Integration editor.

单击 PUBLISH 以在 应用程序集成 编辑器中发布集成。

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:

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

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="..."
)

Note:

注意:

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. 你可以通过生成服务帐户密钥并为服务帐户提供正确的应用程序集成和集成连接器 IAM 角色,来提供服务帐户以代替默认凭据使用。
To find the list of supported entities and actions for a connection, use the Connectors APIs: listActions or listEntityTypes. 要查找连接支持的实体和操作列表,请使用连接器 API: listActions 或 listEntityTypes。

ApplicationIntegrationToolset 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:

ApplicationIntegrationToolset 支持用于集成连接器的 动态 OAuth2 身份验证的 auth_scheme 和 auth_credential。要使用它,请在 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": (
                  "View and manage your data across Google Cloud Platform"
                  " services"
              ),
              "https://www.googleapis.com/auth/calendar.readonly": "View your calendars"
          },
      }
  },
}

oauth_scheme = dict_to_auth_scheme(oauth2_data_google_cloud)

auth_credential = AuthCredential(
  auth_type=AuthCredentialTypes.OAUTH2,
  oauth2=OAuth2Auth(
      client_id="...", #TODO: replace with client_id
      client_secret="...", #TODO: replace with 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:

更新 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="Help user, leverage the tools you have access to",
    tools=[connector_tool],
)

Configure __init__.py to expose your agent:

配置 __init__.py 以公开你的智能体:
```
from . import agent
```
Start the Google ADK Web UI and use your agent:

启动 Google ADK Web UI 并使用你的智能体:
```
# make sure to run `adk web` from your project_root_folder
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).

完成上述步骤后,转到 http://localhost:8000,并选择 my\_agent 智能体(与智能体文件夹名称相同)。

Use Application Integration Workflows¶

使用应用程序集成工作流¶

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

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

1. Create a tool¶

1. 创建工具¶

PythonJava

To create a tool with ApplicationIntegrationToolset in the tools.py file, use the following code:

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

    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 a service account to be used instead of using default credentials. To do this, generate a Service Account Key and provide the correct Application Integration and Integration Connector IAM roles to the service account. For more details about the IAM roles, refer to the Prerequisites section.

注意: 你可以提供服务帐户以代替使用默认凭据。为此,请生成服务帐户密钥并为服务帐户提供正确的应用程序集成和集成连接器 IAM 角色。有关 IAM 角色的更多详细信息,请参阅前提条件部分。

To create a tool with ApplicationIntegrationToolset in the tools.java file, use the following code:

要在 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",
                    "...");
        }
    }

Note: You can provide a service account to be used instead of using default credentials. To do this, generate a Service Account Key and provide the correct Application Integration and Integration Connector IAM roles to the service account. For more details about the IAM roles, refer to the Prerequisites section.

注意: 你可以提供服务帐户以代替使用默认凭据。为此,请生成服务帐户密钥并为服务帐户提供正确的应用程序集成和集成连接器 IAM 角色。有关 IAM 角色的更多详细信息,请参阅前提条件部分。

2. Add the tool to your agent¶

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

PythonJava

To update the agent.py file and add the tool to your agent, use the following code:

要更新 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="Help user, leverage the tools you have access to",
        tools=[integration_tool],
    )

To update the agent.java file and add the tool to your agent, use the following code:

要更新 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) {
            // Assuming Tools class is defined as in the previous step
            ImmutableList<BaseTool> tools = ImmutableList.<BaseTool>builder()
                    .add(Tools.integrationTool)
                    .add(Tools.connectionsTool)
                    .build();

            // Finally, create your agent with the tools generated automatically.
            LlmAgent rootAgent = LlmAgent.builder()
                    .name("science-teacher")
                    .description("Science teacher agent")
                    .model("gemini-2.0-flash")
                    .instruction(
                            "Help user, leverage the tools you have access to."
                    )
                    .tools(tools)
                    .build();

            // You can now use rootAgent to interact with the LLM
            // For example, you can start a conversation with the agent.
        }
    }
```

Note: To find the list of supported entities and actions for a connection, use these Connector APIs: listActions, listEntityTypes.

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

3. Expose your agent¶

3. 公开你的智能体¶

Python

To configure __init__.py to expose your agent, use the following code:

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

    from . import agent

4. Use your agent¶

4. 使用你的智能体¶

PythonJava

To start the Google ADK Web UI and use your agent, use the following commands:

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

    # make sure to run `adk web` from your project_root_folder
    adk web

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

完成上述步骤后,转到 http://localhost:8000,并选择 my_agent 智能体(与智能体文件夹名称相同)。

To start the Google ADK Web UI and use your agent, use the following commands:

要启动 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"

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

完成上述步骤后,转到 http://localhost:8000,并选择 my_agent 智能体(与智能体文件夹名称相同)。