Query Vector Databases with Agents
Let an agent query a VectorStoreIndex directly with natural-language filters and auto-retrieval.
Why it matters
Enable AI agents to query and retrieve data from vector databases. This tool acts as an interface, allowing agents to access and utilize information stored in vector indexes for various applications.
Outcomes
What it gets done
Integrate vector databases into agent workflows.
Retrieve specific data points using natural language queries.
Filter and query vector stores based on metadata.
Provide structured data retrieval for AI agents.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/li-tool-tools-vector-db | bash Overview
VectorDB Tool
A LlamaIndex tool that wraps a VectorStoreIndex and exposes it to an agent for natural-language, metadata-filtered querying. Use when an agent needs to query an already-built vector index with structured metadata filters.
What it does
The VectorDB Tool wraps an existing LlamaIndex VectorStoreIndex and exposes it to an agent as a callable tool, so the agent can query it with natural language and filters to retrieve data rather than the developer wiring up a separate query engine call. VectorDB is initialized directly with the index, and its auto_retrieve_fn is the function the agent actually calls to pull data.
The source's own worked example shows the tool paired with a VectorStoreInfo object that describes the index's content (a brief description like "brief biography of celebrities") and its filterable metadata fields (category, one of Sports/Entertainment/Business/Music, and country, one of a named set of countries). This schema is passed into the tool's description when it's added to the agent's tool list via to_tool_list(func_to_metadata_mapping=...), so the agent knows both what the index contains and which metadata fields it can filter on when deciding how to query it.
When to use - and when NOT to
Use it when you already have a VectorStoreIndex built and want an agent to query it directly - with the option to filter by known metadata fields like category or country - rather than manually constructing retrieval calls. Providing a clear VectorStoreInfo schema is important: it's what lets the agent auto-generate filtered queries instead of blind unfiltered search. Do not use it without first building the VectorStoreIndex; this tool only wraps and exposes an index that already exists.
Capabilities
auto_retrieve_fn retrieves data from the wrapped index, using the index's content description and metadata field schema (from VectorStoreInfo) to support natural-language queries with structured filtering.
How to install
index = VectorStoreIndex(nodes=nodes)
tool_spec = VectorDB(index=index)
Requires an already-built LlamaIndex VectorStoreIndex.
Who it's for
Developers building LlamaIndex agents that need to query an existing vector index with metadata-aware filtering, without manually writing retrieval logic for each query.
Source README
VectorDB Tool
This tool wraps a VectorStoreIndex and enables a agent to call it with queries and filters to retrieve data.
Usage
from llama_index.tools.vector_db import VectorDB
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.core.vector_stores import VectorStoreInfo
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex(nodes=nodes)
tool_spec = VectorDB(index=index)
vector_store_info = VectorStoreInfo(
content_info="brief biography of celebrities",
metadata_info=[
MetadataInfo(
name="category",
type="str",
description="Category of the celebrity, one of [Sports, Entertainment, Business, Music]",
),
MetadataInfo(
name="country",
type="str",
description="Country of the celebrity, one of [United States, Barbados, Portugal]",
),
],
)
agent = FunctionAgent(
tools=tool_spec.to_tool_list(
func_to_metadata_mapping={
"auto_retrieve_fn": ToolMetadata(
name="celebrity_bios",
description=f"""\
Use this tool to look up biographical information about celebrities.
The vector database schema is given below:
{vector_store_info.json()}
{tool_spec.auto_retrieve_fn.__doc__}
""",
fn_schema=create_schema_from_function(
"celebrity_bios", tool_spec.auto_retrieve_fn
),
)
}
),
llm=OpenAI(model="gpt-4.1"),
)
print(
await agent.run("Tell me about two celebrities from the United States. ")
)
auto_retrieve_fn: Retrieves data from the index
This loader is designed to be used as a way to load data as a Tool in a Agent.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.