Skip to content

Update headings and links on Google Cloud Tools page #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 14, 2025
Merged

Update headings and links on Google Cloud Tools page #65

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4888589
Fix link to Connection Tool, formatting and reflowing MD
koverholt Apr 14, 2025
cdeb313
Rework ToC
koverholt Apr 14, 2025
40895a7
Merge branch 'main' into google-cloud-tools-formatting-link
polong-lin Apr 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 122 additions & 59 deletions docs/tools/google-cloud-tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,32 @@
# Google Cloud Tools

Google Cloud tools make it easier to connect your agents to Google Cloud’s products and services. With just a few lines of code you can leverage these tools to connect your agents with:
Google Cloud tools make it easier to connect your agents to Google Cloud’s
products and services. With just a few lines of code you can use these tools to
connect your agents with:

* **millions of custom APIs** which developers host in Apigee,
* **100s** of **prebuilt connectors** to enterprise systems like salesforce, workday and SAP
* **Automation workflows** built using application integration
* Databases like Spanner, AlloyDB, Postgres and more using the MCP Toolbox for databases
* **Millions of custom APIs** that developers host in Apigee.
* **100s** of **prebuilt connectors** to enterprise systems such as Salesforce,
Workday, and SAP.
* **Automation workflows** built using application integration.
* **Databases** such as Spanner, AlloyDB, Postgres and more using the MCP Toolbox for
databases.

![Google Cloud Tools](../assets/google_cloud_tools.svg)

## 1. Use an API from Apigee API Hub
## Apigee API Hub Tools

**ApiHubToolset** lets you turn any documented API from Apigee API hub into a tool with a few lines of code. This section shows you the step by step instructions including setting up authentication for a secure connection to your APIs.
**ApiHubToolset** lets you turn any documented API from Apigee API hub into a
tool with a few lines of code. This section shows you the step by step
instructions including setting up authentication for a secure connection to your
APIs.

## Prerequisites
**Prerequisites**

1. [Install ADK](../get-started/installation.md)
2. Install the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install?db=bigtable-docs#installation_instructions).
3. [Apigee API hub](https://cloud.google.com/apigee/docs/apihub/what-is-api-hub) instance with documented (i.e. OpenAPI spec) APIs
1. [Install ADK](../get-started/installation.md)
2. Install the
[Google Cloud CLI](https://cloud.google.com/sdk/docs/install?db=bigtable-docs#installation_instructions).
3. [Apigee API hub](https://cloud.google.com/apigee/docs/apihub/what-is-api-hub)
instance with documented (i.e. OpenAPI spec) APIs
4. Set up your project structure and create required files

```console
Expand All @@ -30,28 +39,35 @@ project_root_folder
`__ tool.py
```

### Create an API Hub Toolset and add it to your agent
### Create an API Hub Toolset

Note: this tutorial includes an agent creation. If you already have an agent, you can only follow subset of these steps.
Note: This tutorial includes an agent creation. If you already have an agent,
you only need to follow a subset of these steps.

1. Get your access token, so that APIHubToolset can fetch spec from API Hub API. In your terminal run the following command
1. Get your access token, so that APIHubToolset can fetch spec from API Hub API.
In your terminal run the following command

```shell
gcloud auth print-access-token
# Prints your access token like 'ya29....'
```

2. Ensure that the account used has the required permissions. You can use the pre-defined role `roles/apihub.viewer` or assign the following permissions:
1. **apihub.specs.get (required)**
2. apihub.apis.get (optional)
3. apihub.apis.list (optional)
4. apihub.versions.get (optional)
5. apihub.versions.list (optional)
2. Ensure that the account used has the required permissions. You can use the
pre-defined role `roles/apihub.viewer` or assign the following permissions:

1. **apihub.specs.get (required)**
2. apihub.apis.get (optional)
3. apihub.apis.list (optional)
4. apihub.versions.get (optional)
5. apihub.versions.list (optional)
6. apihub.specs.list (optional)

3. Create a tool with `APIHubToolset`. Add the below to `tools.py`

If your API requires authentication, you must configure authentication for the tool. The following code sample demonstrates how to configure an API key. ADK supports token based auth (API Key, Bearer token), service account, and OpenID Connect. We will soon add support for various OAuth2 flows.
If your API requires authentication, you must configure authentication for
the tool. The following code sample demonstrates how to configure an API
key. ADK supports token based auth (API Key, Bearer token), service account,
and OpenID Connect. We will soon add support for various OAuth2 flows.

```py
from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential
Expand All @@ -72,11 +88,20 @@ Note: this tutorial includes an agent creation. If you already have an agent, yo
)
```

For production deployment we recommend using a service account instead of an access token. In the code snippet above, use `service_account_json=service_account_cred_json_str` and provide your security account credentials instead of the token.
For production deployment we recommend using a service account instead of an
access token. In the code snippet above, use
`service_account_json=service_account_cred_json_str` and provide your
security account credentials instead of the token.

For apihub\_resource\_name, if you know the specific ID of the OpenAPI Spec being used for your API, use `` `projects/my-project-id/locations/us-west1/apis/my-api-id/versions/version-id/specs/spec-id` ``. If you would like the Toolset to automatically pull the first available spec from the API, use `` `projects/my-project-id/locations/us-west1/apis/my-api-id` ``
For apihub\_resource\_name, if you know the specific ID of the OpenAPI Spec
being used for your API, use
`` `projects/my-project-id/locations/us-west1/apis/my-api-id/versions/version-id/specs/spec-id` ``.
If you would like the Toolset to automatically pull the first available spec
from the API, use
`` `projects/my-project-id/locations/us-west1/apis/my-api-id` ``

4. Create your agent file [Agent.py](http://Agent.py) and add the created tools to your agent definition:
4. Create your agent file [Agent.py](http://Agent.py) and add the created tools
to your agent definition:

```py
from google.adk.agents.llm_agent import LlmAgent
Expand All @@ -90,13 +115,13 @@ Note: this tutorial includes an agent creation. If you already have an agent, yo
)
```

5. Configure your \`\_\_init\_\_.py\` to expose your agent
5. Configure your \`\_\_init\_\_.py\` to expose your agent

```py
from . import agent
```

6. Start the Google ADK Web UI and try your agent.
6. Start the Google ADK Web UI and try your agent:

```shell
# make sure to run `adk web` from your project_root_folder
Expand All @@ -107,25 +132,36 @@ Note: this tutorial includes an agent creation. If you already have an agent, yo

---

## 2. Connect to Enterprise Applications and Integration workflows
## Application Integration Tools

With **ApplicationIntegrationToolset** you can seamlessly give your agents a
secure and governed to enterprise applications using Integration Connector’s
100+ pre-built connectors for systems like Salesforce, ServiceNow, JIRA, SAP,
and more. Support for both on-prem 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.

With **ApplicationIntegrationToolset** you can seamlessly give your agents a secure and governed to enterprise applications using Integration Connector’s 100+ pre-built connectors for systems like Salesforce, ServiceNow, JIRA, SAP, and more. Support for both on-prem 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**

## Prerequisites
1. [Install ADK](../get-started/installation.md)
2. 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
3. To use tool with default credentials: have Google Cloud CLI installed. See
[installation guide](https://cloud.google.com/sdk/docs/install#installation_instructions)*.*

1. [Install ADK](../get-started/installation.md)
2. 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
3. To use tool with default credentials: have Google Cloud CLI installed. See [installation guide](https://cloud.google.com/sdk/docs/install#installation_instructions)*.*
*Run :*

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

4. Set up your project structure and create required files
4. Set up your project structure and create required files

```console
project_root_folder
Expand All @@ -138,9 +174,16 @@ In addition you can turn your existing Application Integration process automati

When running the agent, make sure to run adk web in project\_root\_folder

### Connect your agent to enterprise applications using [Integration Connectors](https://cloud.google.com/integration-connectors/docs/overview)
### Use Integration Connectors

1. 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](https://pantheon.corp.google.com/integrations/templates/connection-tool/locations/us-central1) from the template library.
Connect your agent to enterprise applications using
[Integration Connectors](https://cloud.google.com/integration-connectors/docs/overview).

1. 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](https://console.cloud.google.com/integrations/templates/connection-tool/locations/us-central1)
from the template library.

2. Create a tool with `ApplicationIntegrationToolset`

Expand All @@ -159,9 +202,11 @@ When running the agent, make sure to run adk web in project\_root\_folder
)
```

Note: You can provide service account to be used instead of using default credentials
To find the list of supported entities and actions for a connection, use the connectors apis:
[listActions](https://cloud.google.com/integration-connectors/docs/reference/rest/v1/projects.locations.connections.connectionSchemaMetadata/listActions), [listEntityTypes](https://cloud.google.com/integration-connectors/docs/reference/rest/v1/projects.locations.connections.connectionSchemaMetadata/listEntityTypes)
Note: You can provide service account to be used instead of using default
credentials To find the list of supported entities and actions for a
connection, use the connectors apis:
[listActions](https://cloud.google.com/integration-connectors/docs/reference/rest/v1/projects.locations.connections.connectionSchemaMetadata/listActions),
[listEntityTypes](https://cloud.google.com/integration-connectors/docs/reference/rest/v1/projects.locations.connections.connectionSchemaMetadata/listEntityTypes)

3. Add the tool to your agent. Update your `agent.py` file

Expand Down Expand Up @@ -190,9 +235,14 @@ When running the agent, make sure to run adk web in project\_root\_folder
adk web
```

Then go to [http://localhost:8000](http://localhost:8000), and choose my\_agent agent (same as the agent folder name)
Then go to [http://localhost:8000](http://localhost:8000), and choose
my\_agent agent (same as the agent folder name)

### Use App Integration Workflows

### Use existing [Application Integration](https://cloud.google.com/application-integration/docs/overview) workflow as a tool for your agent
Use existing
[Application Integration](https://cloud.google.com/application-integration/docs/overview)
workflow as a tool for your agent.

1. Create a tool with `ApplicationIntegrationToolset`

Expand Down Expand Up @@ -237,38 +287,50 @@ When running the agent, make sure to run adk web in project\_root\_folder
adk web
```

Then go to [http://localhost:8000](http://localhost:8000), and choose my\_agent agent (same as the agent folder name)
Then go to [http://localhost:8000](http://localhost:8000), and choose
my\_agent agent (same as the agent folder name)

---

## 3. **Toolbox Tools for Databases**
## Toolbox Tools for Databases

[MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) is an open source MCP server for databases. It was designed with enterprise-grade and production-quality in mind. It enables you to develop tools easier, faster, and more securely by handling the complexities such as connection pooling, authentication, and more.
[MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) is an
open source MCP server for databases. It was designed with enterprise-grade and
production-quality in mind. It enables you to develop tools easier, faster, and
more securely by handling the complexities such as connection pooling,
authentication, and more.

Google’s Agent Development Kit (ADK) has built in support for Toolbox. For more information on [getting started](https://googleapis.github.io/genai-toolbox/getting-started) or [configuring](https://googleapis.github.io/genai-toolbox/getting-started/configure/) Toolbox, see the [documentation](https://googleapis.github.io/genai-toolbox/getting-started/introduction/).
Google’s Agent Development Kit (ADK) has built in support for Toolbox. For more
information on
[getting started](https://googleapis.github.io/genai-toolbox/getting-started) or
[configuring](https://googleapis.github.io/genai-toolbox/getting-started/configure/)
Toolbox, see the
[documentation](https://googleapis.github.io/genai-toolbox/getting-started/introduction/).

![GenAI Toolbox](../assets/mcp_db_toolbox.svg)

## Before you begin

### Configure and deploy Toolbox server
### Configure and deploy

Toolbox is an open source server that you deploy and manage yourself. For more instructions on deploying and configuring, see the official Toolbox documentation:
Toolbox is an open source server that you deploy and manage yourself. For more
instructions on deploying and configuring, see the official Toolbox
documentation:

* [Installing the Server](https://googleapis.github.io/genai-toolbox/getting-started/introduction/#installing-the-server)
* [Installing the Server](https://googleapis.github.io/genai-toolbox/getting-started/introduction/#installing-the-server)
* [Configuring Toolbox](https://googleapis.github.io/genai-toolbox/getting-started/configure/)

### Install client SDK

ADK relies on the `toolbox-langchain` python package to use Toolbox. Install the package before getting started:
ADK relies on the `toolbox-langchain` python package to use Toolbox. Install the
package before getting started:

```shell
pip install toolbox-langchain langchain
```

## Loading Toolbox Tools
### Loading Toolbox Tools

Once you’ve Toolbox server is configured and up and running, you can load tools from your server using the ADK:
Once you’ve Toolbox server is configured and up and running, you can load tools
from your server using the ADK:

```py
from google.adk.tools.toolbox_tool import ToolboxTool
Expand All @@ -280,17 +342,18 @@ tools = toolbox.get_toolset(toolset_name='my-toolset-name'),
# Load single tool
tools = toolbox.get_tool(tool_name='my-tool-name'),

root_agent = Agent(
root_agent = Agent(
...,
tools=tools # Provide the list of tools to the Agent

)
```

## Advanced Toolbox Features
### Advanced Toolbox Features

Toolbox has a variety of features to make developing Gen AI tools for databases. For more information, read more about the following features:
Toolbox has a variety of features to make developing Gen AI tools for databases.
For more information, read more about the following features:

* [Authenticated Parameters](https://googleapis.github.io/genai-toolbox/resources/tools/#authenticated-parameters): bind tool inputs to values from OIDC tokens automatically, making it easy to run sensitive queries without potentially leaking data
* [Authorized Invocations:](https://googleapis.github.io/genai-toolbox/resources/tools/#authorized-invocations) restrict access to use a tool based on the users Auth token
* [Authenticated Parameters](https://googleapis.github.io/genai-toolbox/resources/tools/#authenticated-parameters): bind tool inputs to values from OIDC tokens automatically, making it easy to run sensitive queries without potentially leaking data
* [Authorized Invocations:](https://googleapis.github.io/genai-toolbox/resources/tools/#authorized-invocations) restrict access to use a tool based on the users Auth token
* [OpenTelemetry](https://googleapis.github.io/genai-toolbox/how-to/export_telemetry/): get metrics and tracing from Toolbox with OpenTelemetry