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);
as base64. Use generatedImageWithOptions to set options such as the shape.
import { z } from "zod";
import { GeneratedImage } from "@weaviate/agents";
const AnswerWithImage = z.object({
answer: z.string(),
image: GeneratedImage.describe("An advertisement for the product."),
});
const agent = new QueryAgent(client, { collections: ["ECommerce"] });
const result = await agent.ask("What is the best selling product?", {
outputFormat: AnswerWithImage,
});
const imageBytes = Buffer.from(result.finalAnswerParsed.image.base64, "base64");
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.
To generate an image, include a GeneratedImage field in a Zod schema. The generated image is returned as a base64 PNG on that field's base64 in finalAnswerParsed.
The streamed tokens of the final answer never include base64. It is added after generation, so it only appears in the final state.
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);
}
}
import { z } from "zod";
import { GeneratedImage } from "@weaviate/agents";
const AnswerWithImage = z.object({
answer: z.string(),
image: GeneratedImage.describe("An advertisement for the product."),
});
const agent = new QueryAgent(client, { collections: ["ECommerce"] });
for await (const event of agent.askStream("What is the best selling product?", {
outputFormat: AnswerWithImage,
})) {
if ("finalAnswerParsed" in event) {
const imageBytes = Buffer.from(event.finalAnswerParsed.image.base64, "base64");
} 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.
Optionaleffort?: "medium" | "high" | "ultrahigh"The amount of effort the agent should put into the search. One of "medium", "high", or
"ultrahigh". Higher effort may improve result quality at the expense of increased latency
and cost.
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.