Docs • Reference Guide • Weaviate

Weaviate Agents allow you to automatically interface with your Weaviate collections without writing any complex code.

Installation

This package is to be used in conjunction with the Weaviate TypeScript Client, which is a peer dependency.

npm install weaviate-client weaviate-agents

Or with yarn / pnpm:

yarn add weaviate-client weaviate-agents

pnpm add weaviate-client weaviate-agents

Requires Node 20+ and a Weaviate Cloud cluster.

Query Agent

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

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 askStream() methods, depending on whether your application needs streaming tokens and progress messages.

import weaviate from "weaviate-client";
import { QueryAgent } from "weaviate-agents";

const client = await weaviate.connectToWeaviateCloud(clusterUrl, {
  authCredentials,
});

const qa = new QueryAgent(client, {
  collections: ["FinancialContracts"],
});

const res = await qa.ask("Find all contracts signed in 2025");

Ask mode can be optionally customized with:

• Output formats for structured outputs
• LLM-based evaluation of retrieved sources

Learn more about ask mode in the official documentation.

Search Mode

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.

import { QueryAgent } from "weaviate-agents";

const qa = new QueryAgent(client, {
  collections: ["ECommerce"],
});

const searchResponse = await qa.search("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

Learn more about search mode in the official documentation.

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

Support

• GitHub issues for bug reports and feature requests
• Community forum for questions and discussion

Citation

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}
}

License

BSD 3-Clause