@weaviate/agents
    Preparing search index...

    @weaviate/agents

    Weaviate Agents

    Docs • Reference Guide • Weaviate

    Main Branch npm version

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

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

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

    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:

    • 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

    Support

    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