Initialize the Query Agent.
The Weaviate client connected to a Weaviate Cloud cluster.
Configuration for the agent.
Options for constructing a QueryAgent.
OptionalagentsHost?: stringOptional 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?: stringOptional 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.
Run the Query Agent ask mode.
Performs an agentic search on the collections and returns a natural language answer to the query.
The natural language query string, or a list of chat messages, for the agent.
Optionaloptions: QueryAgentAskOptionsOptions for this ask invocation.
Options for QueryAgent.ask.
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.
OptionalresultEvaluation?: ResultEvaluationHow the agent should evaluate the final result. See ResultEvaluation. Defaults to "none".
An AskModeResponse (or ParsedAskModeResponse when outputFormat is set)
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?",
);
validated into the schema, and exposed (typed) on finalAnswerParsed.
import { z } from "zod";
const CitedText = z.object({
text: z.string(),
sources: z
.array(z.string())
.describe("The sources that support this section of text. Can be empty."),
});
const AnswerWithSources = z.object({ texts: z.array(CitedText) });
const agent = new QueryAgent(client, { collections: ["FinancialContracts"] });
const result = await agent.ask(
"What contracts were signed by Jane Doe in 2024? What were they about?",
{ outputFormat: AnswerWithSources },
);
// result.finalAnswerParsed is typed as { texts: { text: string; sources: string[] }[] }
console.log(result.finalAnswerParsed.texts);
Run the Query Agent ask mode and stream the response.
The natural language query string, or a list of chat messages, for the agent.
Optionaloptions: QueryAgentAskStreamOptions & {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?: booleanWhether to include the final state in the stream. This is the final AskModeResponse, yielded as the last item in the stream.
OptionalincludeProgress?: booleanWhether to include progress messages in the stream. These are informational messages about the progress of the agent's search.
OptionalresultEvaluation?: ResultEvaluationHow the agent should evaluate the final result. See ResultEvaluation. Defaults to "none".
OptionalincludeFinalState?: trueWhether to include the final state in the stream. This is the final AskModeResponse, yielded as the last item in the stream.
OptionalincludeProgress?: trueWhether to include progress messages in the stream. These are informational messages about the progress of the agent's search.
OptionaloutputFormat?: undefinedThe structured output format to return. Either a Zod schema, a JSON Schema object, or undefined.
If a Zod schema is provided, the final answer will be parsed and validated into the schema, and the response will be returned as a ParsedAskModeResponse with the inferred type.
If a JSON Schema object is provided, the final answer will be parsed as JSON, and the response will be returned as a ParsedAskModeResponse with the type Record<string, unknown>.
If undefined, the final answer will be returned as a AskModeResponse with the type string.
An async generator yielding any of the following:
includeProgress is true).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);
}
}
(the default), the final-state event is a ParsedAskModeResponse whose
finalAnswerParsed is typed from the schema.
import { z } from "zod";
const CitedText = z.object({
text: z.string(),
sources: z
.array(z.string())
.describe("The sources that support this section of text. Can be empty."),
});
const AnswerWithSources = z.object({ texts: z.array(CitedText) });
const agent = new QueryAgent(client, { collections: ["FinancialContracts"] });
for await (const event of agent.askStream(
"What contracts were signed by Jane Doe in 2024? What were they about?",
{ outputFormat: AnswerWithSources },
)) {
if ("finalAnswerParsed" in event) {
// ParsedAskModeResponse — finalAnswerParsed is typed from the schema
console.log(event.finalAnswerParsed.texts);
} else if ("delta" in event) {
process.stdout.write(event.delta);
} else {
console.log(event.message);
}
}
Run the query agent.
The natural language query string for the agent.
Options for this run.
Options for QueryAgent.run.
Optionalcollections?: (string | QueryAgentCollectionConfig)[]The collections to query. Will override any collections passed in the constructor.
Optionalcontext?: QueryAgentResponseOptional previous response from the agent.
The response from the query agent.
The run method is deprecated; use ask instead.
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.
The natural language query string, or a list of chat messages, for the agent.
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?: numberOptional 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.
Optionalfiltering?: "recall" | "precision"The filtering strategy to use for the search. "recall" optimizes for finding all relevant
results (broader retrieval), while "precision" optimizes for accuracy of returned results
(narrower, more targeted retrieval).
Optionallimit?: numberThe maximum number of results to return for the first page. Defaults to 20.
A SearchModeResponse for the first page of results. Use
response.next({ limit, offset }) to paginate.
Stream responses from the query agent.
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?: QueryAgentResponseOptional previous response from the agent.
OptionalincludeFinalState?: booleanWhether to include the final state in the stream. This is the final QueryAgentResponse, yielded as the last item in the stream.
OptionalincludeProgress?: booleanWhether to include progress messages in the stream. These are informational messages about the progress of the agent's search.
OptionalincludeFinalState?: trueWhether to include the final state in the stream. This is the final QueryAgentResponse, yielded as the last item in the stream.
OptionalincludeProgress?: trueWhether to include progress messages in the stream. These are informational messages about the progress of the agent's search.
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.
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.
Optionalconversation?: ChatMessage[]Optional conversation history to contextualise suggested queries as follow-up questions.
Each element is a ChatMessage with role and content.
Optionalinstructions?: stringOptional natural language guidance for the style, topic, or language of the suggested queries. Supplied in addition to the agent's system instructions.
OptionalnumQueries?: numberThe number of queries to suggest. Defaults to 3.
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.",
conversation: [
{ role: "user", content: "What topics are covered?" },
{ role: "assistant", content: "The collection covers ML and economics." },
],
});
An agent for executing agentic queries against Weaviate.
For more information, see the Weaviate Agents - Query Agent Docs.