Skip to content

Commit c805942

Browse files
google-genai-botcopybara-github
google-genai-bot
authored and
copybara-github
committed
chore: add contributing spanner sample
PiperOrigin-RevId: 795154839
1 parent e63e2a7 commit c805942

File tree

3 files changed

+201
-0
lines changed

3 files changed

+201
-0
lines changed

‎contributing/samples/spanner/README.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Spanner Tools Sample
2+
3+
## Introduction
4+
5+
This sample agent demonstrates the Spanner first-party tools in ADK,
6+
distributed via the `google.adk.tools.spanner` module. These tools include:
7+
8+
1. `list_table_names`
9+
10+
Fetches Spanner table names present in a GCP Spanner database.
11+
12+
1. `list_table_indexes`
13+
14+
Fetches Spanner table indexes present in a GCP Spanner database.
15+
16+
1. `list_table_index_columns`
17+
18+
Fetches Spanner table index columns present in a GCP Spanner database.
19+
20+
1. `list_named_schemas`
21+
22+
Fetches named schema for a Spanner database.
23+
24+
1. `get_table_schema`
25+
26+
Fetches Spanner database table schema.
27+
28+
1. `execute_sql`
29+
30+
Runs a SQL query in Spanner database.
31+
32+
## How to use
33+
34+
Set up environment variables in your `.env` file for using
35+
[Google AI Studio](https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-ai-studio)
36+
or
37+
[Google Cloud Vertex AI](https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai)
38+
for the LLM service for your agent. For example, for using Google AI Studio you
39+
would set:
40+
41+
* GOOGLE_GENAI_USE_VERTEXAI=FALSE
42+
* GOOGLE_API_KEY={your api key}
43+
44+
### With Application Default Credentials
45+
46+
This mode is useful for quick development when the agent builder is the only
47+
user interacting with the agent. The tools are run with these credentials.
48+
49+
1. Create application default credentials on the machine where the agent would
50+
be running by following https://cloud.google.com/docs/authentication/provide-credentials-adc.
51+
52+
1. Set `CREDENTIALS_TYPE=None` in `agent.py`
53+
54+
1. Run the agent
55+
56+
### With Service Account Keys
57+
58+
This mode is useful for quick development when the agent builder wants to run
59+
the agent with service account credentials. The tools are run with these
60+
credentials.
61+
62+
1. Create service account key by following https://cloud.google.com/iam/docs/service-account-creds#user-managed-keys.
63+
64+
1. Set `CREDENTIALS_TYPE=AuthCredentialTypes.SERVICE_ACCOUNT` in `agent.py`
65+
66+
1. Download the key file and replace `"service_account_key.json"` with the path
67+
68+
1. Run the agent
69+
70+
### With Interactive OAuth
71+
72+
1. Follow
73+
https://developers.google.com/identity/protocols/oauth2#1.-obtain-oauth-2.0-credentials-from-the-dynamic_data.setvar.console_name.
74+
to get your client id and client secret. Be sure to choose "web" as your client
75+
type.
76+
77+
1. Follow https://developers.google.com/workspace/guides/configure-oauth-consent
78+
to add scope "https://www.googleapis.com/auth/spanner.data" and
79+
"https://www.googleapis.com/auth/spanner.admin" as declaration, this is used
80+
for review purpose.
81+
82+
1. Follow
83+
https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred
84+
to add http://localhost/dev-ui/ to "Authorized redirect URIs".
85+
86+
Note: localhost here is just a hostname that you use to access the dev ui,
87+
replace it with the actual hostname you use to access the dev ui.
88+
89+
1. For 1st run, allow popup for localhost in Chrome.
90+
91+
1. Configure your `.env` file to add two more variables before running the
92+
agent:
93+
94+
* OAUTH_CLIENT_ID={your client id}
95+
* OAUTH_CLIENT_SECRET={your client secret}
96+
97+
Note: don't create a separate .env, instead put it to the same .env file that
98+
stores your Vertex AI or Dev ML credentials
99+
100+
1. Set `CREDENTIALS_TYPE=AuthCredentialTypes.OAUTH2` in `agent.py` and run the
101+
agent
102+
103+
## Sample prompts
104+
105+
* Show me all tables in the product_db Spanner database.
106+
* Describe the schema of the product_table table.
107+
* List all indexes on the product_table table.
108+
* Show me the first 10 rows of data from the product_table table.
109+
* Write a query to find the most popular product by joining the product_table and sales_table tables.

‎contributing/samples/spanner/__init__.py

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Copyright 2025 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/spanner/agent.py

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Copyright 2025 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.tools.spanner.settings import Capabilities
20+
from google.adk.tools.spanner.settings import SpannerToolSettings
21+
from google.adk.tools.spanner.spanner_credentials import SpannerCredentialsConfig
22+
from google.adk.tools.spanner.spanner_toolset import SpannerToolset
23+
import google.auth
24+
25+
# Define an appropriate credential type
26+
CREDENTIALS_TYPE = AuthCredentialTypes.OAUTH2
27+
28+
29+
# Define Spanner tool config with read capability set to allowed.
30+
tool_settings = SpannerToolSettings(capabilities=[Capabilities.DATA_READ])
31+
32+
if CREDENTIALS_TYPE == AuthCredentialTypes.OAUTH2:
33+
# Initiaze the tools to do interactive OAuth
34+
# The environment variables OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET
35+
# must be set
36+
credentials_config = SpannerCredentialsConfig(
37+
client_id=os.getenv("OAUTH_CLIENT_ID"),
38+
client_secret=os.getenv("OAUTH_CLIENT_SECRET"),
39+
scopes=[
40+
"https://www.googleapis.com/auth/spanner.admin",
41+
"https://www.googleapis.com/auth/spanner.data",
42+
],
43+
)
44+
elif CREDENTIALS_TYPE == AuthCredentialTypes.SERVICE_ACCOUNT:
45+
# Initialize the tools to use the credentials in the service account key.
46+
# If this flow is enabled, make sure to replace the file path with your own
47+
# service account key file
48+
# https://cloud.google.com/iam/docs/service-account-creds#user-managed-keys
49+
creds, _ = google.auth.load_credentials_from_file("service_account_key.json")
50+
credentials_config = SpannerCredentialsConfig(credentials=creds)
51+
else:
52+
# Initialize the tools to use the application default credentials.
53+
# https://cloud.google.com/docs/authentication/provide-credentials-adc
54+
application_default_credentials, _ = google.auth.default()
55+
credentials_config = SpannerCredentialsConfig(
56+
credentials=application_default_credentials
57+
)
58+
59+
spanner_toolset = SpannerToolset(
60+
credentials_config=credentials_config, spanner_tool_settings=tool_settings
61+
)
62+
63+
# The variable name `root_agent` determines what your root agent is for the
64+
# debug CLI
65+
root_agent = LlmAgent(
66+
model="gemini-2.5-flash",
67+
name="spanner_agent",
68+
description=(
69+
"Agent to answer questions about Spanner database tables and"
70+
" execute SQL queries."
71+
),
72+
instruction="""\
73+
You are a data agent with access to several Spanner tools.
74+
Make use of those tools to answer the user's questions.
75+
""",
76+
tools=[spanner_toolset],
77+
)

0 commit comments

Comments
 (0)