Docs • Reference Guide • Weaviate
Weaviate Agents allow you to automatically interface with your Weaviate collections without writing any complex code.
This package is to be used in conjunction with the Weaviate TypeScript Client. Install @weaviate/node for Node.js or @weaviate/web for browsers; both provide @weaviate/core, which is a peer dependency.
npm install @weaviate/node @weaviate/agents
Or with yarn / pnpm:
yarn add @weaviate/node @weaviate/agents
pnpm add @weaviate/node @weaviate/agents
Requires Node 20+ and a Weaviate Cloud cluster.
The Query Agent turns natural-language questions into precise database operations, making full use of:
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 askStream() methods, depending on whether your application needs streaming tokens and progress messages.
import weaviate from "@weaviate/node";
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:
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.
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:
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
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}
}