# Ask Mode
Weaviate Cloud only
Ask Mode transforms your query into actionable searches or aggregations, and then provides a final answer to the question.
For example, you could ask:
> "How many orders related to books were placed last week?"
And the agent will filter for `orders`, perform semantic search for `books` and sort or filter for timestamps from the last week. Then, the agent will provide a response, answering this question exactly based on the data retrieved.
For more details, see the page for [the Python client](https://weaviate-python-client.readthedocs.io/en/stable/weaviate-agents-python-client/docs/weaviate_agents.query.html#weaviate_agents.query.QueryAgent.ask) or [the Typescript Client](https://weaviate.github.io/agents-typescript-client/classes/QueryAgent.html#ask).
## Usage
Like all features of the Query Agent, it requires instantiation of the `QueryAgent` class, which is connected to your Weaviate `client`. [See the class instantiation page for more detail](../agents-configuration/instantiation.md).
Note, locally running Weaviate instances do not support the Query Agent.
:::code-group{sync="languages"}
```python title="Python"
from weaviate.agents.query import QueryAgent
from weaviate.classes.init import Auth
import weaviate
client = weaviate.connect_to_weaviate_cloud(
cluster_url=os.getenv("WEAVIATE_URL"),
auth_credentials=Auth.api_key(os.getenv("WEAVIATE_API_KEY")),
)
qa = QueryAgent(
client=client,
collections=["Weather"]
)
```
```typescript title="JavaScript/TypeScript"
import weaviate from 'weaviate-client';
import { QueryAgent } from 'weaviate-agents';
```
:::
Make sure to include your API keys in your environment, and specify whichever collection you want to search over.
:::callout{intent="note" title="Async"}
In Python, the Query Agent supports both synchronous and asynchronous usage. The Python examples on this page use the synchronous client, but can be easily replaced with the async equivalents — see the [async section](#async) for details. In JavaScript/TypeScript, all calls are asynchronous by default and use `await`.
:::
### Parameters
The `.ask()` method accepts several arguments:
::::tabs{sync="languages"}
:::tab{title="Python"}
| Parameter | Type | Description |
| ------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | `str \| list[ChatMessage]` | The user query you want the agent to answer. This can be a simple string (`"What is the highest-grossing product?"`) or a list of chat messages (for conversational context). [See the page on multi-turn conversations for more detail](../agents-configuration/multi-turn-conversations.md). |
| `collections` | `list[str \| QueryAgentCollectionConfig] \| None` | The name(s) of the collections to search. You can pass one or many collection names as a list of strings (e.g., `["ECommerce", "BookSales"]`), or provide collection configuration objects for more control. If specified in the `ask` method, it will overwrite those defined in the instantiation of `QueryAgent`. [See the page on collection configuration for more detail](../agents-configuration/advanced-collections.md). |
| `result_evaluation` | `Literal["llm", "none"]` | Controls whether the agent will ask an LLM to "evaluate" the result based on all retrieved context. Accepts either: • `"none"` (default): faster and cheaper; where the final answer is the last LLM call and no further analysis is completed. • `"llm"`: higher cost/latency - enables a final step where an LLM subsets the sources retrieved to only those used in the answer, as well as enabling the optional fields `is_partial_answer` and `missing_information`. See [the response class](#response) for more details. |
| `output_format` | `dict \| type[BaseModel] \| None` | Optional schema for structured output in the final response. When set, `.ask()` returns a `ParsedAskModeResponse` instead of an `AskModeResponse`: the parsed result is added on a new `final_answer_parsed` field, and `final_answer` still holds the raw model output. See [the response class](#response) and [the page on structured outputs for more details](../agents-configuration/structured-outputs.md). |
:::
:::tab{title="JavaScript/TypeScript"}
| Parameter | Type | Description |
| ------------------ | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | `string \| ChatMessage[]` | The user query you want the agent to answer. This can be a simple string (`"What is the highest-grossing product?"`) or a list of chat messages (for conversational context). [See the page on multi-turn conversations for more detail](../agents-configuration/multi-turn-conversations.md). |
| `collections` | `(string \| QueryAgentCollectionConfig)[]` | The name(s) of the collections to search. You can pass one or many collection names as a list of strings (e.g., `["ECommerce", "BookSales"]`), or provide collection configuration objects for more control. [See the page on collection configuration for more detail](../agents-configuration/advanced-collections.md). If specified in the `ask` method, it will overwrite those defined in the instantiation of `QueryAgent`. |
| `resultEvaluation` | `"llm" \| "none"` | Controls whether the agent will ask an LLM to "evaluate" the result based on all retrieved context. Accepts either: • `"none"`: faster and cheaper; default setting where the final answer is the last LLM call. • `"llm"`: higher cost/latency - enables a final step where an LLM subsets the sources retrieved to only those used in the answer, as well as enabling the optional fields `is_partial_answer` and `missing_information`. See [the response class](#response) for more details. |
| `outputFormat` | `ZodType \| object` | Optional schema for structured output in the final response. Pass a [Zod](https://zod.dev/) schema (parsed and validated) or a raw [Draft 2020-12 JSON Schema](https://json-schema.org/draft/2020-12) object (parsed only). When set, `.ask()` returns a `ParsedAskModeResponse` instead of an `AskModeResponse`: the typed result is added on a new `finalAnswerParsed` field, and `finalAnswer` still holds the raw model output. See [the response class](#response) and [the page on structured outputs for more details](../agents-configuration/structured-outputs.md). |
:::
::::
For more advanced searches, you can also specify _additional filters_ within the collection configuration. [See the page on additional filters for more detail](../agents-configuration/additional-filters.md).
These arguments allow you to customize agent behavior, data access, and the type of answer you receive.
## Response
The `AskModeResponse` class has the following properties:
::::tabs{sync="languages"}
:::tab{title="Python"}
| Field | Type | Description |
| --------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `searches` | `list[QueryResultWithCollectionNormalized]` | A list of `QueryResultWithCollectionNormalized`. Each contains full details on the searches carried out during the run. This gives explicit information on the search query, filters, UUID values and sorts that were used, as well as the collection searched on. |
| `aggregations` | `list[AggregationResultWithCollectionNormalized]` | A list of `AggregationResultWithCollectionNormalized`. Each contains full details on the aggregations carried out during the run. This gives explicit information on the group-by property, filters, and aggregation metrics that were used, as well as the collection aggregated on. |
| `usage` | `ModelUnitUsage` | A `ModelUnitUsage` instance providing detail on the model units that were used during the run. The `model_units` are effectively token usage measurements normalized by cost. |
| `total_time` | `float` | Total time taken (seconds). |
| `is_partial_answer` | `bool \| None` | A boolean or null value indicating whether the answer is incomplete or not. Only available if `result_evaluation` is `"llm"`. |
| `missing_information` | `list[str] \| None` | A list of strings detailing what information is missing from the answer that makes it incomplete. Only available if `result_evaluation` is `"llm"`. |
| `final_answer` | `str` | A string comprising the LLM's final answer to the user query. |
| `sources` | `list[Source] \| None` | A list of `Source` objects, which have an `object_id` property correlating to the UUID of the Weaviate object that was retrieved during the run. If `result_evaluation` is `"llm"`, these are subset to only those that are relevant to the `final_answer`. |
[See the client documentation for more detail.](https://weaviate-python-client.readthedocs.io/en/latest/weaviate-agents-python-client/docs/weaviate_agents.classes.html#weaviate_agents.classes.AskModeResponse)
If you provide the `output_format` parameter (`qa.ask(..., output_format=...)`), Ask Mode returns a `ParsedAskModeResponse` instead. It is a subclass of `AskModeResponse`, so it keeps every field above and adds one more. `final_answer` still holds the raw string from the model.
| Field | Type | Description |
| --------------------- | -------------- | -------------------------------------------------------------------- |
| `final_answer_parsed` | `` | The final response, parsed into the schema given in `output_format`. |
The type of `final_answer_parsed` is a `dict` if a dictionary was supplied to `output_format`, otherwise it will be the exact type of the `BaseModel` given.
:::
:::tab{title="JavaScript/TypeScript"}
| Field | Type | Description |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `searches` | `Search[]` | A list of `Search` objects. Each contains full details on the searches carried out during the run. This gives explicit information on the search query, filters, UUID values and sorts that were used, as well as the collection searched on. |
| `aggregations` | `Aggregation[]` | A list of `Aggregation` objects. Each contains full details on the aggregations carried out during the run. This gives explicit information on the group-by property, filters, and aggregation metrics that were used, as well as the collection aggregated on. |
| `usage` | `ModelUnitUsage` | A `ModelUnitUsage` object providing detail on the model units that were used during the run. The `modelUnits` are effectively token usage measurements normalized by cost. |
| `totalTime` | `number` | Total time taken (seconds). |
| `isPartialAnswer` | `boolean` | A boolean indicating whether the answer is incomplete. Only available if `resultEvaluation` is `"llm"`. |
| `missingInformation` | `string[]` | A list of strings detailing what information is missing from the answer that makes it incomplete. Only available if `resultEvaluation` is `"llm"`. |
| `finalAnswer` | `string` | A string comprising the LLM's final answer to the user query. |
| `sources` | `Source[]` | A list of `Source` objects, which have an `objectId` property correlating to the UUID of the Weaviate object that was retrieved during the run. If `resultEvaluation` is `"llm"`, these are subset to only those that are relevant to the `finalAnswer`. |
[See the client documentation for more detail.](https://weaviate.github.io/agents-typescript-client/types/AskModeResponse.html)
If you provide the `outputFormat` parameter (`qa.ask(..., { outputFormat: ... })`), Ask Mode returns a `ParsedAskModeResponse` instead. It is an `AskModeResponse` with one more field, so it keeps every field above. `finalAnswer` still holds the raw string from the model.
| Field | Type | Description |
| ------------------- | -------------- | ------------------------------------------------------------------- |
| `finalAnswerParsed` | `` | The final response, parsed into the schema given in `outputFormat`. |
The type of `finalAnswerParsed` is `Record` if a raw JSON Schema object was supplied to `outputFormat`, otherwise it will be the inferred type of the Zod schema given (`z.infer`).
[See the client documentation for more detail.](https://weaviate.github.io/agents-typescript-client/types/ParsedAskModeResponse.html)
:::
::::
## Streaming
While regular Ask Mode returns a single object, you can choose to stream updates and tokens from the workflow of Ask Mode instead.
:::code-group{sync="languages"}
```python title="Python"
for output in qa.ask_stream("What was the average temperature in the first week of May 2025?"):
pass # Do something with the output
```
```typescript title="JavaScript/TypeScript"
for await (const output of qa.askStream("What was the average temperature in the first week of May 2025?")) {
// Do something with the output
}
```
:::
Since the Query Agent is a multi-layered agentic system, there are different types of streaming payloads you will receive. Each one always has a field that identifies which payload it is, [see below](#responses).
### Request
In addition to the standard Ask Mode arguments ([above](#parameters)), the streaming method accepts two extra flags that control which payload types are emitted:
::::tabs{sync="languages"}
:::tab{title="Python"}
| Parameter | Type | Description |
| --------------------- | ------ | -------------------------------------------------------------------------------------------------------------- |
| `include_progress` | `bool` | Optional. If `True` (default), the agent will stream `ProgressMessage` updates as it processes the query. |
| `include_final_state` | `bool` | Optional. If `True` (default), the agent will emit a final `AskModeResponse` payload at the end of the stream. |
If both `include_progress` and `include_final_state` are set to `false`, the stream will only emit `StreamedTokens` payloads as the final answer is generated.
:::
:::tab{title="JavaScript/TypeScript"}
| Parameter | Type | Description |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------- |
| `includeProgress` | `boolean` | Optional. If `true` (default), the agent will stream `ProgressMessage` updates as it processes the query. |
| `includeFinalState` | `boolean` | Optional. If `true` (default), the agent will emit a final `AskModeResponse` payload at the end of the stream. |
If both `includeProgress` and `includeFinalState` are set to `false`, the stream will only emit `StreamedTokens` payloads as the final answer is generated.
:::
::::
### Responses
::::tabs{sync="languages"}
:::tab{title="Python"}
**`ProgressMessage`** — an update on what part of the system has most recently been completed. A class with four fields:
| Field | Type | Description |
| ------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `output_type` | `Literal["progress_message"]` | Always `progress_message`. |
| `stage` | `str` | One of `query_analysis`, `search`, `aggregation`, or `final_answer`. Identifies the stage at which the agentic service is running. |
| `message` | `str` | A human-readable message describing what the agent is doing. For example, during `query_analysis` this is `"Analyzing query..."`. |
| `details` | `ProgressDetails` | A dictionary providing additional context about each stage.
During the `search` and `aggregation` stages, this typically includes a `"queries"` key — a list of dictionaries, each with: • `query` — the specific search term used. • `collection` — the collection the search was run against.
This lets you see exactly which queries were issued, and against which collections, at each stage. |
[See the client documentation for more detail.](https://weaviate-python-client.readthedocs.io/en/latest/weaviate-agents-python-client/docs/weaviate_agents.classes.html#weaviate_agents.classes.ProgressMessage)
**`StreamedTokens`** — incremental chunks of the final answer as it is generated, letting you render the response token-by-token rather than waiting for it to complete. Each instance has two fields: `output_type` (always `"streamed_tokens"`) and `delta` (the newly generated tokens to append to what you have received so far). [See the client documentation for more detail.](https://weaviate-python-client.readthedocs.io/en/latest/weaviate-agents-python-client/docs/weaviate_agents.classes.html#weaviate_agents.classes.StreamedTokens)
**`AskModeResponse`** — the full response model, [as defined above](#response), with `output_type` always `final_state`. This is always the final result in the stream and indicates the system has completed. [See the client documentation for more detail.](https://weaviate-python-client.readthedocs.io/en/latest/weaviate-agents-python-client/docs/weaviate_agents.classes.html#weaviate_agents.classes.AskModeResponse)
:::
:::tab{title="JavaScript/TypeScript"}
**`ProgressMessage`** — an update on what part of the system has most recently been completed. A class with four fields:
| Field | Type | Description |
| ------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outputType` | `"progressMessage"` | Always `progressMessage`. |
| `stage` | `string` | One of `query_analysis`, `search`, `aggregation`, or `final_answer`. Identifies the stage at which the agentic service is running. |
| `message` | `string` | A human-readable message describing what the agent is doing. For example, during `query_analysis` this is `"Analyzing query..."`. |
| `details` | `ProgressDetails` | An object providing additional context about each stage.
During the `search` and `aggregation` stages, this typically includes a `"queries"` key — a list of objects, each with: • `query` — the specific search term used. • `collection` — the collection the search was run against.
This lets you see exactly which queries were issued, and against which collections, at each stage. |
[See the client documentation for more detail.](https://weaviate.github.io/agents-typescript-client/types/ProgressMessage.html)
**`StreamedTokens`** — incremental chunks of the final answer as it is generated, letting you render the response token-by-token rather than waiting for it to complete. Each instance has two fields: `outputType` (always `"streamedTokens"`) and `delta` (the newly generated tokens to append to what you have received so far). [See the client documentation for more detail.](https://weaviate.github.io/agents-typescript-client/types/StreamedTokens.html)
**`AskModeResponse`** — the full response model, [as defined above](#response), with `outputType` always `finalState`. This is always the final result in the stream and indicates the system has completed. [See the client documentation for more detail.](https://weaviate.github.io/agents-typescript-client/types/AskModeResponse.html)
:::
::::
### Example: Handling different streamed responses
You can handle each streamed payload differently depending on their class, or their output-type property. For example, you may want to display the progress message differently than building the tokens for the final answer.
:::code-group{sync="languages"}
```python title="Python"
from weaviate.agents.classes import ProgressMessage, StreamedTokens, AskModeResponse
def print_stream_output(output):
if isinstance(output, ProgressMessage):
print(output.message)
elif isinstance(output, StreamedTokens):
print(output.delta, end='', flush=True)
elif isinstance(output, AskModeResponse):
output.display()
for output in qa.ask_stream("What was the average temperature in the first week of May 2025?"):
print_stream_output(output)
```
```typescript title="JavaScript/TypeScript"
import { ProgressMessage, StreamedTokens } from 'weaviate-agents';
```
:::
## Async
::::tabs{sync="languages"}
:::tab{title="Python"}
In Python, the above examples use the synchronous client, but Ask Mode can also be called asynchronously. This requires the `AsyncQueryAgent` class (instantiated the same way as its sync counterpart) together with an async Weaviate client.
```python
from weaviate.agents.query import AsyncQueryAgent
async_client = weaviate.use_async_with_weaviate_cloud(
cluster_url=os.environ.get("WEAVIATE_URL"),
auth_credentials=Auth.api_key(os.environ.get("WEAVIATE_API_KEY")),
)
await async_client.connect()
async_qa = AsyncQueryAgent(
client=async_client, collections=["Weather"]
)
```
The `.ask()` method must be awaited:
```python
await async_qa.ask(
query = "What was the average temperature in the first week of May 2025?",
)
```
And the `.ask_stream()` method must be used in an `async for` loop:
```python
async for output in async_qa.ask_stream("What was the average temperature in the first week of May 2025?"):
pass # Do something with the output
```
:::
:::tab{title="JavaScript/TypeScript"}
In JavaScript/TypeScript, the `QueryAgent` is asynchronous by default — the examples in the previous sections already are asynchronous, and no separate async setup is needed.
:::
::::
## Questions and feedback
Have a question or feedback? Here's how to reach us.
::::card-grid
:::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"}
Ask questions and connect with other developers on our **Community forum**.
:::
:::card{title="Support" href="/guides/support-overview" icon="life-buoy"}
Weaviate Cloud user or customer? Find the right channel on the **Support page**.
:::
::::
## Related pages
- [Agents](./agents-index.md)
- [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md)
- [APIs](./apis-index.md)
- [Authorization and authentication](./authorization-and-authentication-index.md)
- [Benchmarks](./benchmarks-index.md)
- [Best practices](./best-practices-index.md)
- [Client libraries](./clients-index.md)
- [Client Libraries / SDKs](./client-libraries-index.md)
- [Cloud](./cloud-index.md)
- [Cloud account management](./cloud-account-management-index.md)
# Agent Instructions
This portal answers questions programmatically. To receive a synthesized,
source-cited answer instead of crawling page by page, append the `?ask=`
query parameter to any page URL on this site:
/guides/quickstart?ask=how+do+I+authenticate
Optional parameters:
- `&goal=` steers the answer toward your
objective (e.g. `&goal=write+a+python+client`).
- `&version=