Docs • Reference Guide • Weaviate
Weaviate Agents allow you to automatically interface with your Weaviate collections without writing any complex code.
This package is a sub-package to be used in conjunction with the Weaviate Python Client. Rather than installing this package directly, you should install it as an optional extra when installing the Weaviate Python Client.
pip install -U "weaviate-client[agents]"If you are having trouble, try to explicitly install/upgrade the agents package via pip install -U weaviate-agents.
Requires Python 3.9+ and a Weaviate Cloud cluster.
The Query Agent turns natural-language questions into precise database operations, making full use of:
- dynamic filters
- cross-collection routing
- query optimization
- aggregations
It returns accurate and relevant results with source citations. It replaces manual query construction and ad-hoc logic with runtime, context-aware planning that optimizes and executes queries across user collections.
Ask mode is natural-language in and natural-language out. It searches or aggregates your data, depending on the user's query, and then answers the question with respect to the retrieved data. This can be accessed using the ask() or ask_stream() methods, depending on whether your application needs streaming tokens and progress messages.
import weaviate
from weaviate.agents.query import QueryAgent
client = weaviate.connect_to_weaviate_cloud(cluster_url=..., auth_credentials=...)
qa = QueryAgent(
client=client,
collections=["FinancialContracts"],
)
res = qa.ask("Find all contracts signed in 2025")Ask mode can be additionally be customized with:
- Output formats for structured outputs
- LLM-based evaluation of retrieved sources
An async version of ask mode is also available with the async client.
Learn more about ask mode in the official documentation.
Search mode is designed for high quality information retrieval with strong recall and controlled precision, without the final-answer generation. This can be accessed using the search() method.
from weaviate.agents.query import QueryAgent
qa = QueryAgent(
client=client,
collections=["ECommerce"],
)
search_response = qa.search(
query="Find me some vintage shoes under $70",
limit=10,
effort="medium",
)Search mode can be optionally customized with:
- Different filtering strategies for recall or precision based search priorities
- Effort level to control search quality versus latency
- Diversity weights to improve diversity amongst results
- Pagination of the results set
An async version of search mode is also available with the async client.
Learn more about search mode in the official documentation.
-
Full documentation for quickstarts, walkthroughs and overviews of how to use the Query Agent
-
Tutorials & Guides for getting started quickly with the Query Agent
-
API reference manual for specific documentation on this client as well as examples
- GitHub issues for bug reports and feature requests
- Community forum for questions and discussion
If you use the Query Agent in your research, please consider citing our paper:
@article{query-agent,
title={Querying databases with function calling},
author={Shorten, Connor and Pierse, Charles and Smith, Thomas Benjamin and D'Oosterlinck, Karel and Celik, Tuana and Cardenas, Erika and Monigatti, Leonie and Hasan, Mohd Shukri and Schmuhl, Edward and Williams, Daniel and others},
journal={arXiv preprint arXiv:2502.00032},
year={2025}
}