diff --git a/docs/tools/google-cloud-tools.md b/docs/tools/google-cloud-tools.md index 8b9641c37..c96c521ae 100644 --- a/docs/tools/google-cloud-tools.md +++ b/docs/tools/google-cloud-tools.md @@ -142,71 +142,109 @@ It supports both on-premise and SaaS applications. In addition, you can turn you ### Prerequisites +#### Step 1: Install ADK + === "Python" -* [Install ADK](../get-started/installation.md). -* Use an existing - [Application Integration](https://cloud.google.com/application-integration/docs/overview) - workflow or - [Integrations Connector](https://cloud.google.com/integration-connectors/docs/overview) - connection you want to use with your agent. -* To use tool with default credentials, install the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install#installation_instructions) and run the following commands: - - ```shell - gcloud config set project - gcloud auth application-default login - gcloud auth application-default set-quota-project - ``` - -* Set up your project structure and create required files. - ```console - 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. +Install the latest version of [ADK](../get-started/installation.md). For information about the latest version of ADK, see [Agent Development Kit Walkthrough](https://docs.google.com/document/d/1oqXkqX9m5wjWE-rkwp-qO0CGpSEQHBTYAYQcWRf91XU/edit?tab=t.0#heading=h.7k9wrm8jpdug). === "Java" -* You must have the Google Cloud CLI installed. For more information, see the [installation - guide](https://cloud.google.com/sdk/docs/install#installation_instructions). -* Run the following commands: +Install the latest version of [ADK](../get-started/installation.md). For information about the latest version of ADK, see [Agent Development Kit Walkthrough](https://docs.google.com/document/d/1oqXkqX9m5wjWE-rkwp-qO0CGpSEQHBTYAYQcWRf91XU/edit?tab=t.0#heading=h.7k9wrm8jpdug). - ```bash - gcloud config set project - gcloud auth application-default login - gcloud auth application-default set-quota-project - ``` -* To use a Connector from Integration Connectors, you need to provision - Application Integration in the same region as your connection. -* Import and publish the [Connection - Tool](https://pantheon.corp.google.com/integrations/templates/connection-tool/locations/us-central1) - from the template library. -* Follow the [Agent Development Kit - Walkthrough](https://docs.google.com/document/d/1oqXkqX9m5wjWE-rkwp-qO0CGpSEQHBTYAYQcWRf91XU/edit?tab=t.0#heading=h.7k9wrm8jpdug) - and use the [latest version of adk](https://github.com/google/adk-python). +#### Step 2: Install CLI + +=== "Python" + +Install [Google Cloud CLI](https://cloud.google.com/sdk/docs/install#installation_instructions). To use the tool with default credentials, run the following commands: + + ```shell + gcloud config set project + gcloud auth application-default login + gcloud auth application-default set-quota-project + ``` + +Replace `` with the unique ID of your Google Cloud project. + +=== "Java" + +Install [Google Cloud CLI](https://cloud.google.com/sdk/docs/install#installation_instructions). To use the tool with default credentials, run the following commands: + + ```bash + gcloud config set project + gcloud auth application-default login + gcloud auth application-default set-quota-project + ``` + +Replace `` with the unique ID of your Google Cloud project. + + +#### Step 3: Provision Application Integration workflow and publish Connection Tool + +=== "Python" + +Use an existing [Application Integration](https://cloud.google.com/application-integration/docs/overview) workflow or [Integrations Connector](https://cloud.google.com/integration-connectors/docs/overview) connection you want to use with your agent. You can also create a new [Application Integration workflow](https://cloud.google.com/application-integration/docs/setup-application-integration) or a [connection](https://cloud.google.com/integration-connectors/docs/connectors/neo4j/configure#configure-the-connector). + +Import and publish the [Connection Tool](https://pantheon.corp.google.com/integrations/templates/connection-tool/locations/us-central1) from the template library. + +**Note**: To use a connector from Integration Connectors, you need to provision Application Integration in the same region as your connection. + +=== "Java" + +Use an existing [Application Integration](https://cloud.google.com/application-integration/docs/overview) workflow or [Integrations Connector](https://cloud.google.com/integration-connectors/docs/overview) connection you want to use with your agent. You can also create a new [Application Integration workflow](https://cloud.google.com/application-integration/docs/setup-application-integration) or a [connection](https://cloud.google.com/integration-connectors/docs/connectors/neo4j/configure#configure-the-connector). + +Import and publish the [Connection Tool](https://pantheon.corp.google.com/integrations/templates/connection-tool/locations/us-central1) from the template library. + +**Note**: To use a connector from Integration Connectors, you need to provision Application Integration in the same region as your connection, import and publish Connection Tool from the template library. + +#### Step 4: Create project structure + +=== "Python" +Set up your project structure and create required files. + ```console + 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`. + +=== "Java" +Set up your project structure and create required files. + ```console + project_root_folder/ + └── my_agent/ + ├── agent.java + └── pom.xml + ``` +When running the agent, make sure to run the commands in the `project\_root_folder`. + +#### Step 5: Set roles and permissions + +=== "Python" + +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. + +=== "Java" + +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. -* The project structure should be as follows: - ``` - project_root_folder/ - └── my_agent/ - ├── agent.java - └── pom.xml - ``` -* When running the agent, make sure you are in the `project_root_f` directory. - ### Use Integration Connectors @@ -214,7 +252,8 @@ Connect your agent to enterprise applications using [Integration Connectors](https://cloud.google.com/integration-connectors/docs/overview). #### 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](https://pantheon.corp.google.com/integrations/list?hl=en&inv=1&invt=Ab2u5g&project=standalone-ip-prod-testing), you must follow these steps to create it: + +**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](https://pantheon.corp.google.com/integrations/list?hl=en&inv=1&invt=Ab2u5g&project=standalone-ip-prod-testing), you must follow these steps to create it: 1. To use a connector from Integration Connectors, click **QUICK SETUP** and [provision](https://console.cloud.google.com/integrations) Application Integration in the same region as your connection. @@ -238,6 +277,7 @@ Connect your agent to enterprise applications using ![Google Cloud Tools](../assets/publish-integration.png) + #### Create an Application Integration Toolset Application Integration Toolset supports `auth_scheme` and `auth_credential` for **dynamic OAuth2 authentication** for Integration Connectors. @@ -351,20 +391,19 @@ After completing the above steps, go to [http://localhost:8000](http://localhost ### Use Application Integration Workflows -Use an existing -[Application Integration](https://cloud.google.com/application-integration/docs/overview) -workflow as a tool for your agent or create a new one. +You can use an existing [Application Integration](https://cloud.google.com/application-integration/docs/overview) workflow as a tool for your agent or create a new one. -#### Create an Application Integration Workflow Toolset +#### Create an Application Integration Toolset and use the agent +To create an Application Integration Toolset and use the agent, do the following: -=== "Python" +#### Step 1: Create a tool -To create an Application Integration Toolset for Application Integration Workflows using Python, follow these steps: +=== "Python" -1. Create a tool with `ApplicationIntegrationToolset` in the `tools.py` file: +To create a tool with `ApplicationIntegrationToolset` in the `tools.py` file, use the following code: - ```py +```py integration_tool = ApplicationIntegrationToolset( project="test-project", # TODO: replace with GCP project of the connection location="us-central1", #TODO: replace with location of the connection @@ -374,49 +413,16 @@ To create an Application Integration Toolset for Application Integration Workflo 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](https://cloud.google.com/iam/docs/keys-create-delete#creating) and providing right [Application Integration and Integration Connector IAM roles](#prerequisites) to the service account. For more details about the IAM roles, refer to the [Prerequisites](#prerequisites) section. - -2. Update the `agent.py` file and add tool to your 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], - ) - ``` - -3. Configure \`\_\_init\_\_.py\` to expose your agent: - - ```py - from . import agent - ``` - -4. Start the Google ADK Web UI and use your agent: - - ```shell - # make sure to run `adk web` from your project_root_folder - adk web - ``` - -After completing the above steps, go to [http://localhost:8000](http://localhost:8000), and choose - ` my\_agent` agent (which is the same as the agent folder name). +``` -=== "Java" + **Note:** You can provide a service account to be used instead of using default credentials. To do this, generate a [Service Account Key](https://cloud.google.com/iam/docs/keys-create-delete#creating) and provide the correct + [Application Integration and Integration Connector IAM roles](#prerequisites) to the service account. For more details about the IAM roles, refer to the [Prerequisites](#prerequisites) section. -To create an Application Integration Toolset for Application Integration -Workflows using Java, follow these steps: +==== "Java" -1. Create a tool with `ApplicationIntegrationToolset` in the `tools.java` file: +To create a tool with `ApplicationIntegrationToolset` in the `tools.java` file, use the following code: - ```java +```java import com.google.adk.tools.applicationintegrationtoolset.ApplicationIntegrationToolset; import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableMap; @@ -451,18 +457,33 @@ Workflows using Java, follow these steps: "..."); } } - ``` +``` + + **Note:** You can provide a service account to be used instead of using default credentials. To do this, generate a [Service Account Key](https://cloud.google.com/iam/docs/keys-create-delete#creating) and provide the correct [Application Integration and Integration Connector IAM roles](#prerequisites) to the service account. For more details about the IAM roles, refer to the [Prerequisites](#prerequisites) section. + +#### Step 2: Add the tool to your agent + +=== "Python" + +To update the `agent.py` file and add the tool to your agent, use the following code: + +```py + from google.adk.agents.llm_agent import LlmAgent + from .tools import integration_tool, connector_tool - **Note:** You can provide service account to be used instead of using - default credentials by generating [Service Account - Key](https://cloud.google.com/iam/docs/keys-create-delete#creating) and - providing right [Application Integration and Integration Connector IAM - roles](#prerequisites) to the service account. For more details about the - IAM roles, refer to the [Prerequisites](#prerequisites) section. + root_agent = LlmAgent( + model='gemini-2.0-flash', + name='integration_agent', + instruction="Help user, leverage the tools you have access to", + tools=[integration_tool], + ) +``` -2. Update the `agent.java` file and add tool to your agent: + ==== "Java" + + To update the `agent.java` file and add the tool to your agent, use the following code: - ```java +```java import com.google.adk.agent.LlmAgent; import com.google.adk.tools.BaseTool; import com.google.common.collect.ImmutableList; @@ -490,25 +511,46 @@ Workflows using Java, follow these steps: // For example, you can start a conversation with the agent. } } - ``` - - **Note:** To find the list of supported entities and actions for a +``` + **Note:** To find the list of supported entities and actions for a connection, use these Connector APIs: `listActions`, `listEntityTypes`. -3. Start the Google ADK Web UI and use your agent: +#### Step 3: Expose your agent + +==== "Python" + +To configure `__init__.py` to expose your agent, use the following code: + +```py + from . import agent +``` + +#### Step 4: Use your agent + +=== "Python" + +To start the Google ADK Web UI and use your agent, use the following commands: - ```bash +```shell + # make sure to run `adk web` from your project_root_folder + adk web +``` +After completing the above steps, go to [http://localhost:8000](http://localhost:8000), and choose the `my_agent` agent (which is the same as the agent folder name). + +=== "Java" + +To start the Google ADK Web UI and use your agent, use the following commands: + +```bash 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](http://localhost:8000), and choose `my_agent` agent -(which is the same as the agent folder name). +After completing the above steps, go to [http://localhost:8000](http://localhost:8000), and choose the `my_agent` agent (which is the same as the agent folder name). ---