weaviate-agents
    Preparing search index...

    Class QueryAgent

    An agent for executing agentic queries against Weaviate.

    For more information, see the Weaviate Agents - Query Agent Docs.

    Index

    Constructors

    constructor

    Methods

    ask askStream run search stream suggestQueries

    Constructors

    • Initialize the Query Agent.

      Parameters

      • client: WeaviateClient

        The Weaviate client connected to a Weaviate Cloud cluster.

      • options: QueryAgentOptions = {}

        Configuration for the agent.

        Options for constructing a QueryAgent.

        • OptionalagentsHost?: string

          Optional host of the agents service.

        • Optionalcollections?: QueryAgentCollection[]

          The collections to query. Either a list of strings, or a list of QueryAgentCollectionConfig objects. Will be overridden if passed in any of the agent's methods that support it.

        • OptionalsystemPrompt?: string

          Optional prompt to control the tone, format, and style of the agent's final response. This prompt is both passed to the query writer agent, and applied when generating the answer after all research and data retrieval is complete.

      Returns QueryAgent

    Methods

    • Run the Query Agent ask mode.

      Performs an agentic search on the collections and returns a natural language answer to the query.

      Parameters

      Returns Promise<AskModeResponse>

      An AskModeResponse which contains the final answer, sources, and other metadata such as the searches performed, usage and total time.

      const agent = new QueryAgent(client, { collections: ["FinancialContracts"] });
      const response = await agent.ask(
        "What are the terms of the contract signed by John Smith in May 2025?",
      );

    • Run the Query Agent ask mode and stream the response.

      Parameters

      • query: QueryAgentQuery

        The natural language query string, or a list of chat messages, for the agent.

      • Optionaloptions: QueryAgentAskStreamOptions & {
            includeFinalState?: true;
            includeProgress?: true;
        }

        Options for the ask stream.

        Options for QueryAgent.askStream.

        • Optionalcollections?: (string | QueryAgentCollectionConfig)[]

          The collections to query. Either a list of strings, or a list of QueryAgentCollectionConfig objects. Will override any collections passed in the constructor.

        • OptionalincludeFinalState?: boolean

          Whether to include the final state in the stream. This is the final AskModeResponse, yielded as the last item in the stream.

        • OptionalincludeProgress?: boolean

          Whether to include progress messages in the stream. These are informational messages about the progress of the agent's search.

        • OptionalresultEvaluation?: ResultEvaluation

          How the agent should evaluate the final result. See ResultEvaluation. Defaults to "none".

        • OptionalincludeFinalState?: true

          Whether to include the final state in the stream. This is the final AskModeResponse, yielded as the last item in the stream.

        • OptionalincludeProgress?: true

          Whether to include progress messages in the stream. These are informational messages about the progress of the agent's search.

      Returns AsyncGenerator<AskModeResponse | ProgressMessage | StreamedTokens>

      An async generator yielding any of the following:

      • ProgressMessage: informational messages about the progress of the agent's search (if includeProgress is true).
      • StreamedTokens: token deltas from the agent's response.
      • AskModeResponse: the final response, yielded as the last item in the stream (if includeFinalState is true).
      const agent = new QueryAgent(client, { collections: ["FinancialContracts"] });
      for await (const event of agent.askStream(
        "What are the terms of the contract signed by John Smith in May 2025?",
      )) {
        if ("finalAnswer" in event) {
          // AskModeResponse
          console.log(event.finalAnswer);
        } else if ("delta" in event) {
          // StreamedTokens
          process.stdout.write(event.delta);
        } else {
          // ProgressMessage
          console.log(event.message);
        }
      }

    • Run the Query Agent search-only mode.

      Sends the initial search request and returns a SearchModeResponse containing the first page of results. To paginate, call response.next({ limit, offset }) on the returned response. This reuses the same underlying searches to ensure a consistent result set across pages.

      Parameters

      • query: QueryAgentQuery

        The natural language query string, or a list of chat messages, for the agent.

      • options: QueryAgentSearchOnlyOptions = {}

        Options for this search invocation.

        Options for QueryAgent.search.

        • Optionalcollections?: (string | QueryAgentCollectionConfig)[]

          The collections to query. Either a list of strings, or a list of QueryAgentCollectionConfig objects. Will override any collections passed in the constructor.

        • OptionaldiversityWeight?: number

          Optional number between 0.0 and 1.0 to diversify results with MMR reranking. Higher values push for more topical variety at the cost of relevance. Defaults to no diversity.

        • Optionallimit?: number

          The maximum number of results to return for the first page. Defaults to 20.

      Returns Promise<SearchModeResponse>

      A SearchModeResponse for the first page of results. Use response.next({ limit, offset }) to paginate.

      const agent = new QueryAgent(client, { collections: ["FinancialContracts"] });
      const page1 = await agent.search("Find all NDAs signed by Jane Doe in 2024.", { limit: 5 });
      const page2 = await page1.next({ limit: 5, offset: 5 });
      const page3 = await page2.next({ limit: 5, offset: 10 });

    • Stream responses from the query agent.

      Parameters

      • query: string

        The natural language query string for the agent.

      • Optionaloptions: QueryAgentStreamOptions & { includeFinalState?: true; includeProgress?: true }

        Options for the stream.

        Options for QueryAgent.stream.

        • Optionalcollections?: (string | QueryAgentCollectionConfig)[]

          The collections to query. Will override any collections passed in the constructor.

        • Optionalcontext?: QueryAgentResponse

          Optional previous response from the agent.

        • OptionalincludeFinalState?: boolean

          Whether to include the final state in the stream. This is the final QueryAgentResponse, yielded as the last item in the stream.

        • OptionalincludeProgress?: boolean

          Whether to include progress messages in the stream. These are informational messages about the progress of the agent's search.

        • OptionalincludeFinalState?: true

          Whether to include the final state in the stream. This is the final QueryAgentResponse, yielded as the last item in the stream.

        • OptionalincludeProgress?: true

          Whether to include progress messages in the stream. These are informational messages about the progress of the agent's search.

      Returns AsyncGenerator<QueryAgentResponse | ProgressMessage | StreamedTokens>

      An async generator yielding ProgressMessage, StreamedTokens, and a final QueryAgentResponse, depending on the include flags.

      The stream method is deprecated; use askStream instead.

    • Suggest queries for the data in your collections.

      Uses the agent to generate example queries that can be run against the given collections. This can help users discover what kinds of questions they can ask, or generate example prompts for a dataset.

      Parameters

      • options: QueryAgentSuggestQueriesOptions = {}

        Options for the suggest-queries request.

        Options for QueryAgent.suggestQueries.

        • Optionalcollections?: (string | QueryAgentCollectionConfig)[]

          Optional override for the collections configured at instantiation. Either a list of strings, or a list of QueryAgentCollectionConfig objects.

        • Optionalinstructions?: string

          Optional natural language guidance for the style, topic, or language of the suggested queries. Supplied in addition to the agent's system instructions.

        • OptionalnumQueries?: number

          The number of queries to suggest. Defaults to 3.

      Returns Promise<SuggestQueryResponse>

      A SuggestQueryResponse containing the list of suggested queries, along with additional metadata if present.

      const agent = new QueryAgent(client, { collections: ["FinancialContracts"] });
      const suggestions = await agent.suggestQueries({
        collections: ["Products"],
        numQueries: 5,
        instructions: "Focus on questions about eco-friendly features.",
      });

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods