weaviate_agents.query

class weaviate_agents.query.AsyncQueryAgent(client, collections=None, agents_host=None, system_prompt=None, timeout=None)[source]

Bases: _BaseQueryAgent[WeaviateAsyncClient]

An agent for executing agentic queries against Weaviate.

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

Initialize the asynchronous Query Agent.

Parameters:

client (WeaviateAsyncClient) – The asynchronous Weaviate client connected to a Weaviate Cloud cluster (i.e. from weaviate.use_async_with_weaviate_cloud).
collections (list[str | QueryAgentCollectionConfig] | None) – 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.
agents_host (str | None) – Optional host of the agents service.
system_prompt (str | None) – 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.
timeout (int | None) – The timeout for the request. Defaults to 60 seconds.

async run(query, collections=None, context=None)[source]

Deprecated: the `run` method is deprecated; use `ask` instead.

Run the query agent.

Parameters:

query (str) – The natural language query string for the agent.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Will override any collections if passed in the constructor.
context (QueryAgentResponse | None) – Optional previous response from the agent.

Return type:

QueryAgentResponse

async ask(query, collections=None, result_evaluation='none')[source]

Run the Query Agent ask mode.

Perform an agentic search on the collections and return a natural language answer to the query.

Parameters:

query (str | list[ChatMessage]) – The natural language query string for the agent.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Will override any collections if passed in the constructor.
result_evaluation (Literal['llm', 'none']) – One of "llm" or "none". If "llm", the final answer will be cross-compared to the sources, and those sources will be filtered to only those in the answer. Also populates the fields missing_information and is_partial_answer of the response. If "none", the result will not be evaluated, and the sources will not be filtered. Defaults to "none".

Returns:

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

Return type:

AskModeResponse

Examples

>>> from weaviate_agents import AsyncQueryAgent
>>> agent = AsyncQueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> await agent.ask("What are the terms of the contract signed by John Smith in May 2025?")

stream(query, collections=None, context=None, include_progress=True, include_final_state=True)[source]

Deprecated: the `stream` method is deprecated; use `ask_stream` instead.

Stream from the query agent.

Parameters:

query (str) – The natural language query string for the agent.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Will override any collections if passed in the constructor.
context (QueryAgentResponse | None) – Optional previous response from the agent.
include_progress (bool) – Whether to include progress messages in the stream. These are informational messages about the progress of the agent’s search.
include_final_state (bool) – Whether to include the final state in the stream. This is the final response class, QueryAgentResponse, that will be the last item in the stream.

async ask_stream(query, collections=None, include_progress=True, include_final_state=True, result_evaluation='none')[source]

Run the Query Agent ask mode and stream the response.

Parameters:

query (str | list[ChatMessage]) – The natural language query string for the agent.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Either a list of strings, or a list of QueryAgentCollectionConfig objects. Will override any collections if passed in the constructor.
include_progress (bool) – Whether to include progress messages in the stream. These are informational messages about the progress of the agent’s search.
include_final_state (bool) – Whether to include the final state in the stream. This is the final response class that will be the last item in the stream.
result_evaluation (Literal['llm', 'none']) – One of "llm" or "none". If "llm", the final answer will be cross-compared to the sources, and those sources will be filtered to only those in the answer. Also populates the fields missing_information and is_partial_answer of the response. If "none", the result will not be evaluated, and the sources will not be filtered. Defaults to "none".

Returns:

A generator of the response stream. The generator will yield the following types:

[ProgressMessage]: Informational messages about the progress of the agent’s search (if include_progress is True).
[AskModeResponse]: The final response class that will be the last item in the stream (if include_final_state is True).
[StreamedTokens]: Token deltas from the agent’s response.

Examples

>>> from weaviate_agents import AsyncQueryAgent
>>> from weaviate_agents.classes import AskModeResponse, StreamedTokens, ProgressMessage
>>> agent = AsyncQueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> async for result in agent.ask_stream("What are the terms of the contract signed by John Smith in May 2025?"):
...     if isinstance(result, AskModeResponse):
...         result.display()
...     elif isinstance(result, StreamedTokens):
...         print(result.delta, end='', flush=True)
...     elif isinstance(result, ProgressMessage):
...         print(result.message)

async research_stream(query, collections=None, reasoning_prompt=None, include_progress=True, include_thoughts=True, include_final_state=True)[source]

Run the Query Agent research mode and stream the response.

Parameters:

query (str | list[ChatMessage]) – The natural language query string or list of chat messages.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Overrides any collections provided in the constructor when set.
reasoning_prompt (str | None) – Optional prompt to control the agent’s behavior during the research phase, guiding how it searches, retrieves, and reasons about data. The constructor’s system_prompt controls the final response formatting.
include_progress (bool) – Whether to include progress messages in the stream. These are informational messages about the progress of the agent’s search.
include_thoughts (bool) – Whether to include streamed thoughts in the stream. These are token deltas of the agent’s reasoning process as it performs the research.
include_final_state (bool) – Whether to include the final state in the stream. This is the final response class, ResearchModeResponse, that will be the last item in the stream.

Returns:

A generator of the response stream. The generator will yield the following types:

[ProgressMessage]: Informational messages about the progress of the agent’s search (if include_progress is True).
[StreamedThoughts]: Token deltas of the agent’s reasoning process as it performs the research (if include_thoughts is True).
[ResearchModeResponse]: The final response class that will be the last item in the stream (if include_final_state is True).
[StreamedTokens]: Token deltas from the agent’s response.

Examples

>>> from weaviate_agents import AsyncQueryAgent
>>> from weaviate_agents.classes import StreamedThoughts, StreamedTokens, ProgressMessage, ResearchModeResponse
>>> agent = AsyncQueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> async for result in agent.research_stream("What are the terms of the contract signed by John Smith in May 2025?"):
...     if isinstance(result, ResearchModeResponse):
...         result.display()
...     elif isinstance(result, StreamedThoughts):
...         print(result.delta, end='', flush=True)
...     elif isinstance(result, StreamedTokens):
...         print(result.delta, end='', flush=True)
...     elif isinstance(result, ProgressMessage):
...         print(result.message)

async search(query, limit=20, collections=None, filtering=None, diversity_weight=None)[source]

Run the Query Agent search-only mode.

This method sends the initial search request and returns an AsyncSearchModeResponse containing the first page of results. To paginate, use the AsyncSearchModeResponse.next() method. This reuses the same underlying searches to ensure a consistent result set across pages.

Parameters:

query (str | list[ChatMessage]) – The natural language query string for the agent.
limit (int) – The maximum number of results to return for the first page.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Overrides any collections provided in the constructor when set.
filtering (Literal['recall', 'precision'] | None) – The filtering strategy to use for this search. Use “recall” to optimize for finding all relevant results, or “precision” to optimize for the accuracy of returned results. Defaults to “recall”.
diversity_weight (float | None) – Optional float 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 None (no diversity).

Returns:

An instance of AsyncSearchModeResponse for the first page of results. Use the await response.next(limit=..., offset=...) method to paginate.

Return type:

AsyncSearchModeResponse

Examples

>>> from weaviate_agents import AsyncQueryAgent
>>> agent = AsyncQueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> await agent.search("Find all NDAs signed by Jane Doe in 2024.")

>>> from weaviate_agents import AsyncQueryAgent
>>> agent = AsyncQueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> # With pagination
>>> page_1 = await agent.search("Find all NDAs signed by Jane Doe in 2024.", limit = 5)
>>> page_2 = await page_1.next(limit = 5, offset = 5)
>>> page_3 = await page_2.next(limit = 5, offset = 10)

async suggest_queries(collections=None, num_queries=3, instructions=None)[source]

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:

collections (list[str | QueryAgentCollectionConfig] | None) – Optional override for the collections configured at instantiation. Can be a list of collection names (str) or QueryAgentCollectionConfig objects.
num_queries (int) – The number of queries to suggest (default: 3).
instructions (str | None) – Optional natural language guidance for the style, topic, or language of the suggested queries. This is supplied in addition to the agent’s system instructions.

Returns:

An instance of SuggestQueryResponse which contains a list of suggested queries, with additional metadata if present.

Return type:

SuggestQueryResponse

Examples

>>> from weaviate_agents import AsyncQueryAgent
>>> agent = AsyncQueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> await agent.suggest_queries(
...     collections=["Products"],
...     num_queries=5,
...     instructions="Focus on questions about eco-friendly features.",
... )

>>> from weaviate_agents import AsyncQueryAgent
>>> agent = AsyncQueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> await agent.suggest_queries(
...     collections=["FinancialContracts"],
...     num_queries=1,
...     instructions="Write your question in Spanish.",
... )

class weaviate_agents.query.QueryAgent(client, collections=None, agents_host=None, system_prompt=None, timeout=None)[source]

Bases: _BaseQueryAgent[WeaviateClient]

An agent for executing agentic queries against Weaviate.

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

Initialize the synchronous Query Agent.

Parameters:

client (WeaviateClient) – The synchronous Weaviate client connected to a Weaviate Cloud cluster (i.e. from weaviate.connect_to_weaviate_cloud).
collections (list[str | QueryAgentCollectionConfig] | None) – 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.
agents_host (str | None) – Optional host of the agents service.
system_prompt (str | None) – 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.
timeout (int | None) – The timeout for the request. Defaults to 60 seconds.

run(query, collections=None, context=None)[source]

Deprecated: the `run` method is deprecated; use `ask` instead.

Run the query agent.

Parameters:

query (str) – The natural language query string for the agent.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Will override any collections if passed in the constructor.
context (QueryAgentResponse | None) – Optional previous response from the agent.

Return type:

QueryAgentResponse

ask(query, collections=None, result_evaluation='none')[source]

Run the Query Agent ask mode.

Perform an agentic search on the collections and return a natural language answer to the query.

Parameters:

query (str | list[ChatMessage]) – The natural language query string for the agent.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Either a list of strings, or a list of QueryAgentCollectionConfig objects. Will override any collections if passed in the constructor.
result_evaluation (Literal['llm', 'none']) – One of "llm" or "none". If "llm", the final answer will be cross-compared to the sources, and those sources will be filtered to only those in the answer. Also populates the fields missing_information and is_partial_answer of the response. If "none", the result will not be evaluated, and the sources will not be filtered. Defaults to "none".

Returns:

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

Return type:

AskModeResponse

Examples

>>> from weaviate_agents import QueryAgent
>>> agent = QueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> agent.ask("What are the terms of the contract signed by John Smith in May 2025?")

stream(query, collections=None, context=None, include_progress=True, include_final_state=True)[source]

Deprecated: the `stream` method is deprecated; use `ask_stream` instead.

Stream from the query agent.

Parameters:

query (str) – The natural language query string for the agent.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Will override any collections if passed in the constructor.
context (QueryAgentResponse | None) – Optional previous response from the agent.
include_progress (bool) – Whether to include progress messages in the stream. These are informational messages about the progress of the agent’s search.
include_final_state (bool) – Whether to include the final state in the stream. This is the final response class, QueryAgentResponse, that will be the last item in the stream.

ask_stream(query, collections=None, include_progress=True, include_final_state=True, result_evaluation='none')[source]

Run the Query Agent ask mode and stream the response.

Parameters:

query (str | list[ChatMessage]) – The natural language query string for the agent.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Either a list of strings, or a list of QueryAgentCollectionConfig objects. Will override any collections if passed in the constructor.
include_progress (bool) – Whether to include progress messages in the stream. These are informational messages about the progress of the agent’s search.
include_final_state (bool) – Whether to include the final state in the stream. This is the final response class that will be the last item in the stream.
result_evaluation (Literal['llm', 'none']) – One of "llm" or "none". If "llm", the final answer will be cross-compared to the sources, and those sources will be filtered to only those in the answer. Also populates the fields missing_information and is_partial_answer of the response. If "none", the result will not be evaluated, and the sources will not be filtered. Defaults to "none".

Returns:

A generator of the response stream. The generator will yield the following types:

[ProgressMessage]: Informational messages about the progress of the agent’s search (if include_progress is True).
[AskModeResponse]: The final response class that will be the last item in the stream (if include_final_state is True).
[StreamedTokens]: Token deltas from the agent’s response.

Examples

>>> from weaviate_agents import QueryAgent
>>> from weaviate_agents.classes import AskModeResponse, StreamedTokens, ProgressMessage
>>> agent = QueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> for result in agent.ask_stream("What are the terms of the contract signed by John Smith in May 2025?"):
...     if isinstance(result, AskModeResponse):
...         result.display()
...     elif isinstance(result, StreamedTokens):
...         print(result.delta, end='', flush=True)
...     elif isinstance(result, ProgressMessage):
...         print(result.message)

research_stream(query, collections=None, reasoning_prompt=None, include_progress=True, include_thoughts=True, include_final_state=True)[source]

Run the Query Agent research mode and stream the response.

Parameters:

query (str | list[ChatMessage]) – The natural language query string or list of chat messages.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Overrides any collections provided in the constructor when set.
reasoning_prompt (str | None) – Optional prompt to control the agent’s behavior during the research phase, guiding how it searches, retrieves, and reasons about data. The constructor’s system_prompt controls the final response formatting.
include_progress (bool) – Whether to include progress messages in the stream. These are informational messages about the progress of the agent’s search.
include_thoughts (bool) – Whether to include streamed thoughts in the stream. These are token deltas of the agent’s reasoning process as it performs the research.
include_final_state (bool) – Whether to include the final state in the stream. This is the final response class, ResearchModeResponse, that will be the last item in the stream.

Returns:

A generator of the response stream. The generator will yield the following types:

[ProgressMessage]: Informational messages about the progress of the agent’s search (if include_progress is True).
[StreamedThoughts]: Token deltas of the agent’s reasoning process as it performs the research (if include_thoughts is True).
[ResearchModeResponse]: The final response class that will be the last item in the stream (if include_final_state is True).
[StreamedTokens]: Token deltas from the agent’s response.

Examples

>>> from weaviate_agents import QueryAgent
>>> from weaviate_agents.classes import StreamedThoughts, StreamedTokens, ProgressMessage, ResearchModeResponse
>>> agent = QueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> for result in agent.research_stream("What are the terms of the contract signed by John Smith in May 2025?"):
...     if isinstance(result, ResearchModeResponse):
...         result.display()
...     elif isinstance(result, StreamedThoughts):
...         print(result.delta, end='', flush=True)
...     elif isinstance(result, StreamedTokens):
...         print(result.delta, end='', flush=True)
...     elif isinstance(result, ProgressMessage):
...         print(result.message)

search(query, limit=20, collections=None, filtering=None, diversity_weight=None)[source]

Run the Query Agent search-only mode.

This method sends the initial search request and returns a SearchModeResponse containing the first page of results. To paginate, use the SearchModeResponse.next() method. This reuses the same underlying searches to ensure a consistent result set across pages.

Parameters:

query (str | list[ChatMessage]) – The natural language query string for the agent.
limit (int) – The maximum number of results to return for the first page.
collections (list[str | QueryAgentCollectionConfig] | None) – The collections to query. Either a list of strings, or a list of QueryAgentCollectionConfig objects. Overrides any collections provided in the constructor when set.
filtering (Literal['recall', 'precision'] | None) – The filtering strategy to use for this search. Use “recall” to optimize for finding all relevant results, or “precision” to optimize for the accuracy of returned results. Defaults to “recall”.
diversity_weight (float | None) – Optional float 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 None (no diversity).

Returns:

An instance of SearchModeResponse for the first page of results. Use the response.next(limit=..., offset=...) method to paginate.

Return type:

SearchModeResponse

Examples

>>> from weaviate_agents import QueryAgent
>>> agent = QueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> agent.search("Find all NDAs signed by Jane Doe in 2024.")

>>> from weaviate_agents import QueryAgent
>>> agent = QueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> # With pagination
>>> page_1 = agent.search("Find all NDAs signed by Jane Doe in 2024.", limit = 5)
>>> page_2 = page_1.next(limit = 5, offset = 5)
>>> page_3 = page_2.next(limit = 5, offset = 10)

suggest_queries(collections=None, num_queries=3, instructions=None)[source]

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:

collections (list[str | QueryAgentCollectionConfig] | None) – Optional override for the collections configured at instantiation. Can be a list of collection names (str) or QueryAgentCollectionConfig objects.
num_queries (int) – The number of queries to suggest (default: 3).
instructions (str | None) – Optional natural language guidance for the style, topic, or language of the suggested queries. This is supplied in addition to the agent’s system instructions.

Returns:

An instance of SuggestQueryResponse which contains a list of suggested queries, with additional metadata if present.

Return type:

SuggestQueryResponse

Examples

>>> from weaviate_agents import QueryAgent
>>> agent = QueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> agent.suggest_queries(
...     collections=["Products"],
...     num_queries=5,
...     instructions="Focus on questions about eco-friendly features.",
... )

>>> from weaviate_agents import QueryAgent
>>> agent = QueryAgent(
...     client=client,
...     collections=["FinancialContracts"],
... )
>>> agent.suggest_queries(
...     collections=["FinancialContracts"],
...     num_queries=1,
...     instructions="Write your question in Spanish.",
... )

class weaviate_agents.query.AsyncQueryAgentSearcher(headers, connection_headers, timeout, query_url, query, collections, system_prompt, filtering=None, diversity_weight=None)[source]

Bases: _BaseQueryAgentSearcher

A configured async searcher for the Query Agent search-only mode.

This configured search can be run using the run method. This allows you to paginate through the results set multiple times with different limit / offset values. This will result in the same underlying searches being performed each time, resulting in a consistent results set across pages.

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

Parameters:

headers (dict[str, Any])
connection_headers (dict[str, str])
timeout (int)
query_url (str)
query (Union[str, list[ChatMessage]])
collections (list[Union[str, QueryAgentCollectionConfig]])
system_prompt (Optional[str])
filtering (Optional[Literal['recall', 'precision']])
diversity_weight (Optional[float])

async run(limit=20, offset=0)[source]

Run the search-only agent with the given limit and offset values.

Calling this method multiple times on the same AsyncQueryAgentSearcher instance will result in the same underlying searches being performed each time, allowing you to paginate over a consistent results set.

Parameters:

limit (int) – The maximum number of results to return. If not specified, this defaults to 20.
offset (int) – The offset to start from. If not specified, the retrieval begins from the first object in the results set.

Returns:

An AsyncSearchModeResponse object containing the results of the search, the usage, and the underlying searches performed.

Return type:

AsyncSearchModeResponse

class weaviate_agents.query.QueryAgentSearcher(headers, connection_headers, timeout, query_url, query, collections, system_prompt, filtering=None, diversity_weight=None)[source]

Bases: _BaseQueryAgentSearcher

A configured searcher for the Query Agent search-only mode.

This configured search can be run using the run method. This allows you to paginate through the results set multiple times with different limit / offset values. This will result in the same underlying searches being performed each time, resulting in a consistent results set across pages.

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

Parameters:

headers (dict[str, Any])
connection_headers (dict[str, str])
timeout (int)
query_url (str)
query (Union[str, list[ChatMessage]])
collections (list[Union[str, QueryAgentCollectionConfig]])
system_prompt (Optional[str])
filtering (Optional[Literal['recall', 'precision']])
diversity_weight (Optional[float])

run(limit=20, offset=0)[source]

Run the search-only agent with the given limit and offset values.

Calling this method multiple times on the same QueryAgentSearcher instance will result in the same underlying searches being performed each time, allowing you to paginate over a consistent results set.

Parameters:

limit (int) – The maximum number of results to return. If not specified, this defaults to 20.
offset (int) – The offset to start from. If not specified, the retrieval begins from the first object in the results set.

Returns:

A SearchModeResponse object containing the results of the search, the usage, and the underlying searches performed.

Return type:

SearchModeResponse

Subpackages

weaviate_agents.query.classes