Skip to content

Commit fb19e1a

Browse files
google-genai-botcopybara-github
google-genai-bot
authored and
copybara-github
committed
feat: add GCS first party toolset to ADK integrations
GCS toolset supports basic operations to interact with GCS buckets and objects. PiperOrigin-RevId: 930830041
1 parent 66e00db commit fb19e1a

22 files changed

Lines changed: 2181 additions & 0 deletions

‎contributing/samples/integrations/gcs/README.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# GCS Tools Sample
2+
3+
## Introduction
4+
5+
This sample agent demonstrates the Google Cloud Storage (GCS) first-party tools in ADK,
6+
distributed via the `google.adk.integrations.gcs` module. These tools include:
7+
8+
1. `gcs_get_bucket`
9+
10+
Get metadata information about a GCS bucket.
11+
12+
1. `gcs_list_objects`
13+
14+
List object names in a GCS bucket.
15+
16+
1. `gcs_get_object_metadata`
17+
18+
Get metadata information about a GCS object (blob).
19+
20+
## How to use
21+
22+
Set up environment variables in your `.env` file for using
23+
[Google AI Studio](https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-ai-studio)
24+
or
25+
[Google Cloud Vertex AI](https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai)
26+
for the LLM service for your agent. For example, for using Google AI Studio you
27+
would set:
28+
29+
- GOOGLE_GENAI_USE_ENTERPRISE=FALSE
30+
- GOOGLE_API_KEY={your api key}
31+
32+
### With Application Default Credentials (gcloud)
33+
34+
This is the easiest way to use your own Google Cloud identity for both the tools AND the LLM.
35+
36+
1. Install the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install).
37+
1. Run `gcloud auth application-default login` in your terminal.
38+
1. Configure your environment to use Vertex AI (which supports ADC) instead of AI Studio:
39+
- `export GOOGLE_GENAI_USE_ENTERPRISE=TRUE`
40+
- `export GOOGLE_CLOUD_PROJECT={your-project-id}`
41+
1. Ensure the Vertex AI API is enabled and you have the correct permissions:
42+
- Enable API: `gcloud services enable aiplatform.googleapis.com`
43+
- Grant Role: `gcloud projects add-iam-policy-binding {your-project-id} --member="user:{your-email}" --role="roles/aiplatform.user"`
44+
1. Set `CREDENTIALS_TYPE = None` in `agent.py`.
45+
1. Run the agent.
46+
47+
### With Service Account Keys
48+
49+
This mode is useful for quick development when the agent builder wants to run
50+
the agent with service account credentials. The tools are run with these
51+
credentials.
52+
53+
1. Create service account key by following https://cloud.google.com/iam/docs/service-account-creds#user-managed-keys.
54+
55+
1. Set `CREDENTIALS_TYPE=AuthCredentialTypes.SERVICE_ACCOUNT` in `agent.py`
56+
57+
1. Download the key file and replace `"service_account_key.json"` with the path
58+
59+
1. Run the agent
60+
61+
### With Interactive OAuth
62+
63+
1. Follow
64+
https://developers.google.com/identity/protocols/oauth2#1.-obtain-oauth-2.0-credentials-from-the-dynamic_data.setvar.console_name.
65+
to get your client id and client secret. Be sure to choose "web" as your client
66+
type.
67+
68+
1. Follow https://developers.google.com/workspace/guides/configure-oauth-consent
69+
to add scope "https://www.googleapis.com/auth/cloud-platform" and
70+
"https://www.googleapis.com/auth/devstorage.full_control" as a declaration, this is used
71+
for review purpose.
72+
73+
1. Follow
74+
https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred
75+
to add http://localhost/dev-ui/ to "Authorized redirect URIs".
76+
77+
Note: localhost here is just a hostname that you use to access the dev ui,
78+
replace it with the actual hostname you use to access the dev ui.
79+
80+
1. For 1st run, allow popup for localhost in Chrome.
81+
82+
1. Configure your `.env` file to add two more variables before running the
83+
agent:
84+
85+
- OAUTH_CLIENT_ID={your client id}
86+
- OAUTH_CLIENT_SECRET={your client secret}
87+
88+
Note: don't create a separate .env, instead put it to the same .env file that
89+
stores your Vertex AI or Dev ML credentials
90+
91+
1. Set `CREDENTIALS_TYPE=AuthCredentialTypes.OAUTH2` in `agent.py` and run the
92+
agent
93+
94+
## Sample prompts
95+
96+
- Show me metadata for the my-bucket bucket.
97+
- List all objects in the my-bucket bucket.
98+
- Get metadata for the my-object.txt object in my-bucket.
99+
- Download the GCS object my-object.txt in my-bucket to a local file ~/Downloads/downloaded.txt.
100+
- Upload my local file /tmp/local_report.pdf to my-bucket as report.pdf.

‎contributing/samples/integrations/gcs/__init__.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
from . import agent

‎contributing/samples/integrations/gcs/agent.py‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import os
16+
17+
from google.adk.agents.llm_agent import LlmAgent
18+
from google.adk.auth.auth_credential import AuthCredentialTypes
19+
from google.adk.integrations.gcs import GCSToolset
20+
from google.adk.integrations.gcs.gcs_credentials import GCSCredentialsConfig
21+
from google.adk.integrations.gcs.settings import Capabilities
22+
from google.adk.integrations.gcs.settings import GCSToolSettings
23+
import google.auth
24+
25+
# Define an appropriate credential type.
26+
# Set to None to use Application Default Credentials (ADC).
27+
# This is the recommended way to use your `gcloud` credentials locally:
28+
# Run `gcloud auth application-default login` in your terminal first.
29+
CREDENTIALS_TYPE = None
30+
31+
# Define GCS tool config (default is READ_ONLY; add Capabilities.READ_WRITE for modification access)
32+
tool_settings = GCSToolSettings(capabilities=[Capabilities.READ_WRITE])
33+
34+
if CREDENTIALS_TYPE == AuthCredentialTypes.OAUTH2:
35+
# Initialize the tools to do interactive OAuth
36+
# The environment variables OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET
37+
# must be set
38+
credentials_config = GCSCredentialsConfig(
39+
client_id=os.getenv("OAUTH_CLIENT_ID"),
40+
client_secret=os.getenv("OAUTH_CLIENT_SECRET"),
41+
scopes=[
42+
"https://www.googleapis.com/auth/cloud-platform",
43+
"https://www.googleapis.com/auth/devstorage.full_control",
44+
],
45+
)
46+
elif CREDENTIALS_TYPE == AuthCredentialTypes.SERVICE_ACCOUNT:
47+
# Initialize the tools to use the credentials in the service account key.
48+
# If this flow is enabled, make sure to replace the file path with your own
49+
# service account key file
50+
# https://cloud.google.com/iam/docs/service-account-creds#user-managed-keys
51+
creds, _ = google.auth.load_credentials_from_file("service_account_key.json")
52+
credentials_config = GCSCredentialsConfig(credentials=creds)
53+
else:
54+
# Initialize the tools to use the application default credentials.
55+
# https://cloud.google.com/docs/authentication/provide-credentials-adc
56+
application_default_credentials, _ = google.auth.default()
57+
credentials_config = GCSCredentialsConfig(
58+
credentials=application_default_credentials
59+
)
60+
61+
gcs_toolset = GCSToolset(
62+
credentials_config=credentials_config, gcs_tool_settings=tool_settings
63+
)
64+
65+
# The variable name `root_agent` determines what your root agent is for the
66+
# debug CLI
67+
root_agent = LlmAgent(
68+
model="gemini-2.5-flash",
69+
name="gcs_agent",
70+
description=(
71+
"Agent to answer questions about Google Cloud Storage (GCS) buckets"
72+
" and objects."
73+
),
74+
instruction="""\
75+
You are a storage agent with access to several GCS tools.
76+
Make use of those tools to answer the user's questions about buckets and objects.
77+
""",
78+
tools=[
79+
gcs_toolset,
80+
],
81+
)

‎contributing/samples/integrations/gcs_admin/README.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# GCS Admin Tools Sample
2+
3+
## Introduction
4+
5+
This sample agent demonstrates the Google Cloud Storage (GCS) administrative tools in ADK,
6+
distributed via the `google.adk.integrations.gcs` module. These tools include:
7+
8+
1. `gcs_list_buckets`
9+
10+
List GCS bucket names in a Google Cloud project.
11+
12+
1. `gcs_create_bucket`
13+
14+
Create a new GCS bucket.
15+
16+
1. `gcs_update_bucket`
17+
18+
Update properties of a GCS bucket.
19+
20+
1. `gcs_delete_bucket`
21+
22+
Delete a GCS bucket.
23+
24+
## How to use
25+
26+
Set up environment variables in your `.env` file for using
27+
[Google AI Studio](https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-ai-studio)
28+
or
29+
[Google Cloud Vertex AI](https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai)
30+
for the LLM service for your agent. For example, for using Google AI Studio you
31+
would set:
32+
33+
- GOOGLE_GENAI_USE_ENTERPRISE=FALSE
34+
- GOOGLE_API_KEY={your api key}
35+
36+
### With Application Default Credentials (gcloud)
37+
38+
This is the easiest way to use your own Google Cloud identity for both the tools AND the LLM.
39+
40+
1. Install the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install).
41+
1. Run `gcloud auth application-default login` in your terminal.
42+
1. Configure your environment to use Vertex AI (which supports ADC) instead of AI Studio:
43+
- `export GOOGLE_GENAI_USE_ENTERPRISE=TRUE`
44+
- `export GOOGLE_CLOUD_PROJECT={your-project-id}`
45+
1. Ensure the Vertex AI API is enabled and you have also the correct permissions:
46+
- Enable API: `gcloud services enable aiplatform.googleapis.com`
47+
- Grant Role: `gcloud projects add-iam-policy-binding {your-project-id} --member="user:{your-email}" --role="roles/aiplatform.user"`
48+
1. Set `CREDENTIALS_TYPE = None` in `agent.py`.
49+
1. Run the agent.
50+
51+
### With Service Account Keys
52+
53+
This mode is useful for quick development when the agent builder wants to run
54+
the agent with service account credentials. The tools are run with these
55+
credentials.
56+
57+
1. Create service account key by following https://cloud.google.com/iam/docs/service-account-creds#user-managed-keys.
58+
59+
1. Set `CREDENTIALS_TYPE=AuthCredentialTypes.SERVICE_ACCOUNT` in `agent.py`
60+
61+
1. Download the key file and replace `"service_account_key.json"` with the path
62+
63+
1. Run the agent
64+
65+
### With Interactive OAuth
66+
67+
1. Follow
68+
https://developers.google.com/identity/protocols/oauth2#1.-obtain-oauth-2.0-credentials-from-the-dynamic_data.setvar.console_name.
69+
to get your client id and client secret. Be sure to choose "web" as your client
70+
type.
71+
72+
1. Follow https://developers.google.com/workspace/guides/configure-oauth-consent
73+
to add scope "https://www.googleapis.com/auth/cloud-platform" and
74+
"https://www.googleapis.com/auth/devstorage.full_control" as a declaration, this is used
75+
for review purpose.
76+
77+
1. Follow
78+
https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred
79+
to add http://localhost/dev-ui/ to "Authorized redirect URIs".
80+
81+
Note: localhost here is just a hostname that you use to access the dev ui,
82+
replace it with the actual hostname you use to access the dev ui.
83+
84+
1. For 1st run, allow popup for localhost in Chrome.
85+
86+
1. Configure your `.env` file to add two more variables before running the
87+
agent:
88+
89+
- OAUTH_CLIENT_ID={your client id}
90+
- OAUTH_CLIENT_SECRET={your client secret}
91+
92+
Note: don't create a separate .env, instead put it to the same .env file that
93+
stores your Vertex AI or Dev ML credentials
94+
95+
1. Set `CREDENTIALS_TYPE=AuthCredentialTypes.OAUTH2` in `agent.py` and run the
96+
agent
97+
98+
## Sample prompts
99+
100+
- List all buckets in the my-project project.
101+
- Create a new bucket named my-bucket in my-project.
102+
- Enable versioning and uniform bucket-level access on my-bucket.
103+
- Delete the GCS bucket my-bucket.

‎contributing/samples/integrations/gcs_admin/__init__.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
from . import agent

0 commit comments

Comments
 (0)