Skip to content

Commit 7458d68

Browse files
zyantwkoverholt
zyantw
and
koverholt
authored
#1029 - 8 vector_store_similarity_search and SpannerVectorStoreSettings (#1926)
* #1029 - 8 vector_store_similarity_search and SpannerVectorStoreSettings Added vector_store_similarity_search to SpannerToolset. SpannerVectorStoreSettings is introduced to support this feature. * Update spanner.md * Update spanner.md Applied feedback. Additionally, reviewed the phrasing in the intro for clarity and concision and did some minor formatting edits. * Fix wrapping, missing import, trailing whitespace, formatting fixes * Restructure Spanner page: add intro, section headings, reorder vector search * Add experimental tags/notes to corresponding integration pages --------- Co-authored-by: Kristopher Overholt <koverholt@google.com>
1 parent 452c15f commit 7458d68

5 files changed

Lines changed: 139 additions & 14 deletions

File tree

‎docs/integrations/bigtable.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ catalog_tags: ["data", "google"]
88
# Bigtable tool for ADK
99

1010
<div class="language-support-tag">
11-
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.12.0</span>
11+
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.12.0</span><span class="lst-preview">Experimental</span>
1212
</div>
1313

1414
These are a set of tools aimed to provide integration with Bigtable, namely:
@@ -23,6 +23,9 @@ These are a set of tools aimed to provide integration with Bigtable, namely:
2323

2424
They are packaged in the toolset `BigtableToolset`.
2525

26+
!!! example "Experimental"
27+
This feature is experimental and may be updated in future releases.
28+
2629
```py
2730
--8<-- "examples/python/snippets/tools/built-in-tools/bigtable.py"
2831
```

‎docs/integrations/data-agent.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,16 @@ catalog_tags: ["data", "google"]
88
# Google Cloud Data Agents tool for ADK
99

1010
<div class="language-support-tag">
11-
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.23.0</span>
11+
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.23.0</span><span class="lst-preview">Experimental</span>
1212
</div>
1313

1414
These are a set of tools aimed to provide integration with Data Agents powered by [Conversational Analytics API](https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/overview).
1515

1616
Data Agents are AI-powered agents that help you analyze your data using natural language. When configuring a Data Agent, you can choose from supported data sources, including **BigQuery**, **Looker**, and **Looker Studio**.
1717

18+
!!! example "Experimental"
19+
This feature is experimental and may be updated in future releases.
20+
1821
**Prerequisites**
1922

2023
Before using these tools, you must build and configure your Data Agents in Google Cloud:

‎docs/integrations/pubsub.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,16 @@ catalog_tags: ["google"]
88
# Google Cloud Pub/Sub tool for ADK
99

1010
<div class="language-support-tag">
11-
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.22.0</span>
11+
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.22.0</span><span class="lst-preview">Experimental</span>
1212
</div>
1313

1414
The `PubSubToolset` allows agents to interact with
1515
[Google Cloud Pub/Sub](https://cloud.google.com/pubsub)
1616
service to publish, pull, and acknowledge messages.
1717

18+
!!! example "Experimental"
19+
This feature is experimental and may be updated in future releases.
20+
1821
## Prerequisites
1922

2023
Before using the `PubSubToolset`, you need to:

‎docs/integrations/spanner.md‎

Lines changed: 126 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,137 @@ catalog_tags: ["data","google"]
88
# Google Cloud Spanner tool for ADK
99

1010
<div class="language-support-tag">
11-
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.11.0</span>
11+
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.11.0</span><span class="lst-preview">Experimental</span>
1212
</div>
1313

14-
These are a set of tools aimed to provide integration with Spanner, namely:
14+
[Google Cloud Spanner](https://cloud.google.com/spanner) is a fully managed,
15+
distributed database with support for SQL and vector search. The ADK Spanner
16+
tools let your agent explore database schemas, run SQL queries, and perform
17+
vector similarity search against your Spanner data.
1518

16-
* **`list_table_names`**: Fetches table names present in a GCP Spanner database.
17-
* **`list_table_indexes`**: Fetches table indexes present in a GCP Spanner database.
18-
* **`list_table_index_columns`**: Fetches table index columns present in a GCP Spanner database.
19-
* **`list_named_schemas`**: Fetches named schema for a Spanner database.
20-
* **`get_table_schema`**: Fetches Spanner database table schema and metadata information.
21-
* **`execute_sql`**: Runs a SQL query in Spanner database and fetch the result.
22-
* **`similarity_search`**: Similarity search in Spanner using a text query.
19+
!!! example "Experimental"
20+
This feature is experimental and may be updated in future releases.
2321

24-
They are packaged in the toolset `SpannerToolset`.
22+
## Available tools
23+
24+
The `SpannerToolset` provides the following tools:
25+
26+
- **`list_table_names`**: Fetches table names present in a GCP Spanner database.
27+
- **`list_table_indexes`**: Fetches table indexes present in a GCP Spanner
28+
database.
29+
- **`list_table_index_columns`**: Fetches table index columns present in a GCP
30+
Spanner database.
31+
- **`list_named_schemas`**: Fetches named schema for a Spanner database.
32+
- **`get_table_schema`**: Fetches Spanner database table schema and metadata
33+
information.
34+
- **`execute_sql`**: Runs a SQL query in Spanner database and fetch the result.
35+
- **`similarity_search`**: Similarity search in Spanner using a text query.
36+
37+
## Use with agent
2538

2639
```py
2740
--8<-- "examples/python/snippets/tools/built-in-tools/spanner.py"
2841
```
42+
43+
## Vector similarity search
44+
45+
The `vector_store_similarity_search` tool enables agents to perform semantic
46+
searches against a Spanner table configured as a vector store. This capability
47+
is essential for building contextually aware RAG applications; it allows AI
48+
models to retrieve database context based on semantic meaning rather than exact
49+
keyword matches. By configuring `SpannerVectorStoreSettings`, your agents can
50+
better understand the intent behind user queries and ground their responses in
51+
the most relevant Spanner data.
52+
53+
The following example configures a Spanner table as a vector store and wires the
54+
`vector_store_similarity_search` tool into a RAG agent:
55+
56+
```py
57+
from google.adk.agents import LlmAgent
58+
from google.adk.tools.spanner import SpannerCredentialsConfig, SpannerToolset
59+
from google.adk.tools.spanner.settings import (
60+
Capabilities,
61+
SpannerToolSettings,
62+
SpannerVectorStoreSettings,
63+
)
64+
65+
# 1. Define Spanner tool config with vector store settings
66+
my_vector_store_settings = SpannerVectorStoreSettings(
67+
project_id="your-gcp-project",
68+
instance_id="your-spanner-instance",
69+
database_id="your-database",
70+
table_name="my_products",
71+
content_column="productDescription",
72+
embedding_column="productDescriptionEmbedding",
73+
vector_length=768,
74+
vertex_ai_embedding_model_name="text-embedding-005",
75+
selected_columns=["productId", "productName", "productDescription"],
76+
nearest_neighbors_algorithm="EXACT_NEAREST_NEIGHBORS",
77+
top_k=3,
78+
distance_type="COSINE",
79+
additional_filter="inventoryCount > 0",
80+
)
81+
82+
my_tool_settings = SpannerToolSettings(
83+
capabilities=[Capabilities.DATA_READ],
84+
vector_store_settings=my_vector_store_settings,
85+
)
86+
87+
# 2. Initialize the Spanner toolset
88+
credentials_config = SpannerCredentialsConfig()
89+
my_spanner_toolset = SpannerToolset(
90+
credentials_config=credentials_config,
91+
spanner_tool_settings=my_tool_settings,
92+
tool_filter=["vector_store_similarity_search"],
93+
)
94+
95+
# 3. Use the toolset in your RAG agent
96+
my_rag_agent = LlmAgent(
97+
model="gemini-flash-latest",
98+
name="product_search_agent",
99+
instruction="""
100+
You are a helpful assistant that answers user questions by finding similar products.
101+
1. Always use the `vector_store_similarity_search` tool to find relevant product information.
102+
2. If no relevant information is found, state that no matching products were found.
103+
3. Present the relevant product details clearly in your response.
104+
""",
105+
tools=[my_spanner_toolset],
106+
)
107+
```
108+
109+
### Configuration
110+
111+
The `SpannerVectorStoreSettings` class used above defines how
112+
`vector_store_similarity_search` operates. It accepts the following parameters:
113+
114+
#### Required parameters
115+
116+
- **`project_id`**: Your Google Cloud Project ID required for authentication
117+
context.
118+
- **`instance_id`**: The Spanner instance ID.
119+
- **`database_id`**: The Spanner database ID.
120+
- **`table_name`**: The Spanner table containing the vector embeddings.
121+
- **`embedding_column`**: The `ARRAY<FLOAT>` or `ARRAY<DOUBLE>` column where the
122+
vector embeddings are stored.
123+
- **`content_column`**: The column containing the original text or content to be
124+
retrieved.
125+
- **`vector_length`**: The dimensionality of your embedding vectors that must
126+
match your model.
127+
- **`vertex_ai_embedding_model_name`**: The model used to generate the
128+
embeddings, for example "text-embedding-005".
129+
130+
#### Optional parameters
131+
132+
- **`selected_columns`**: A list of columns you can include in the search
133+
results, such as metadata or identifiers.
134+
- **`nearest_neighbors_algorithm`**: The algorithm you use for the search, such
135+
as `EXACT_NEAREST_NEIGHBORS` and `APPROXIMATE_NEAREST_NEIGHBORS`.
136+
- **`num_leaves_to_search`**: Number of index leaf nodes searched. Only used
137+
with `APPROXIMATE_NEAREST_NEIGHBORS`.
138+
- **`vector_search_index_settings`**: Vector index settings. Only required with
139+
`APPROXIMATE_NEAREST_NEIGHBORS`.
140+
- **`top_k`**: The number of nearest neighbors to retrieve per query.
141+
- **`distance_type`**: The distance metric used for similarity calculation, such
142+
as `COSINE` or `EUCLIDEAN`.
143+
- **`additional_filter`**: An optional SQL filter string to apply during the
144+
search, for example: "inventoryCount > 0".

‎examples/python/snippets/tools/built-in-tools/spanner.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ def count_rows_tool(
9797
description=(
9898
"Agent to answer questions about Spanner database and execute SQL queries."
9999
),
100-
instruction="""\
100+
instruction="""
101101
You are a data assistant agent with access to several Spanner tools.
102102
Make use of those tools to answer the user's questions.
103103
""",

0 commit comments

Comments
 (0)