weaviate · g-despot · Jun 2, 2026 · May 25, 2026 · May 28, 2026 · May 28, 2026
diff --git a/docs/agents/_includes/code/query_agent.mts b/docs/agents/_includes/code/query_agent.mts
@@ -147,9 +147,15 @@ for (const obj of basicSearchResponse.searchResults.objects) {
 // END BasicSearchQuery
 
 // START DiversityRanking
+// Diversity ranking needs a vectorizer it can resolve. Scope the call to a
+// single collection with a target vector so the agent knows what to use.
 const diversitySearchResponse = await qa.search("summer shoes", {
     limit: 10,
-    diversityWeight: 0.5
+    diversityWeight: 0.5,
+    collections: [{
+        name: "ECommerce",
+        targetVector: ["name_description_brand_vector"],
+    }],
 })
 
 // Access the search results
@@ -349,7 +355,7 @@ if (!basicResponse.finalAnswer || basicResponse.finalAnswer === '') {
 
 // START SuggestQueries
 const suggestResponse = await qa.suggestQueries({
-    collections: ["IRPAPERS"],
+    collections: ["FinancialContracts"],
     numQueries: 3,
     instructions: "High-level themes and open-ended exploration",
 });

diff --git a/docs/agents/_includes/code/query_agent.py b/docs/agents/_includes/code/query_agent.py
@@ -273,6 +273,12 @@
     "summer shoes",
     limit=10,
     diversity_weight=0.5,
+    collections=[
+        QueryAgentCollectionConfig(
+            name="ECommerce",
+            target_vector=["name_description_brand_vector"],
+        )
+    ],
 )
 
 # Access the search results
@@ -364,12 +370,18 @@
 import asyncio
 import os
 import weaviate
+from weaviate.classes.init import Auth
 from weaviate.agents.query import AsyncQueryAgent
 
+# Provide any inference-provider keys your collections' vectorizers / generative
+# models need; an empty dict is fine if the cluster uses Weaviate Embeddings.
+headers = {
+    "X-OpenAI-API-Key": os.environ.get("OPENAI_API_KEY", ""),
+}
 
 async_client = weaviate.use_async_with_weaviate_cloud(
     cluster_url=os.environ.get("WEAVIATE_URL"),
-    auth_credentials=os.environ.get("WEAVIATE_API_KEY"),
+    auth_credentials=Auth.api_key(os.environ.get("WEAVIATE_API_KEY")),
     headers=headers,
 )
 
@@ -492,7 +504,7 @@ async def run_streaming_query():
 
 # START SuggestQueries
 response = qa.suggest_queries(
-    collections=["IRPAPERS"],
+    collections=["FinancialContracts"],
     num_queries=3,
     instructions="High-level themes and open-ended exploration",
 )

diff --git a/docs/agents/_includes/code/search_mode.mts b/docs/agents/_includes/code/search_mode.mts
@@ -52,6 +52,10 @@ for (const obj of searchResponse.searchResults.objects) {
 const diversitySearchResponse = await qa.search("summer shoes", {
     limit: 10,
     diversityWeight: 0.5,
+    collections: [{
+        name: "ECommerce",
+        targetVector: ["name_description_brand_vector"],
+    }],
 });
 
 for (const obj of diversitySearchResponse.searchResults.objects) {
@@ -87,4 +91,15 @@ pages.forEach((pageResponse, index) => {
 });
 // END SearchPagination
 
+// START FilteringExample
+const filteringResponse = await qa.search("Find me some vintage shoes under $70", {
+    filtering: "precision",
+    limit: 10,
+});
+
+for (const obj of filteringResponse.searchResults.objects) {
+    console.log(`Product: ${obj.properties['name']} - $${obj.properties['price']}`);
+}
+// END FilteringExample
+
 await client.close();
diff --git a/docs/agents/_includes/code/search_mode.py b/docs/agents/_includes/code/search_mode.py
@@ -96,6 +96,17 @@
     print()
 # END SearchPagination
 
+# START FilteringExample
+search_response = qa.search(
+    "Find me some vintage shoes under $70",
+    filtering="precision",
+    limit=10,
+)
+
+for obj in search_response.search_results.objects:
+    print(f"Product: {obj.properties['name']} - ${obj.properties['price']}")
+# END FilteringExample
+
 # --- Async code examples in string as top-level await doesn't work, full code will be executed in 
 # asyncio.run below
 

diff --git a/docs/agents/_includes/code/suggest_queries.py b/docs/agents/_includes/code/suggest_queries.py
@@ -61,6 +61,7 @@ async def _async_run_for_testing():
     import weaviate
     from weaviate.classes.init import Auth
     from weaviate.agents.query import AsyncQueryAgent
+    from weaviate.agents.classes import QueryAgentCollectionConfig
 
     async_client = weaviate.use_async_with_weaviate_cloud(
         cluster_url=os.environ.get("WEAVIATE_URL"),

diff --git a/docs/agents/clients/index.md b/docs/agents/clients/index.md
@@ -1,6 +1,6 @@
 ---
 title: Agents clients
-description: "Use the Python or TypeScript client to interact with Weaviate Agents."
+description: "Use the Python or TypeScript client to interact with the Query Agent."
 image: og/docs/agents.jpg
 tags: ['agents', 'query-agent', 'clients']
 ---
@@ -14,13 +14,13 @@ export const agentsClientLibrariesData = [
   {
     title: "Python Client",
     description:
-      "Install and use the official Weaviate Agents Python client.",
+      "Install and use the official Query Agent Python client.",
     link: "/agents/clients/python/",
     icon: "fab fa-python",
   },
   {
     title: "JavaScript / TypeScript Client",
-    description: "Use the official Weaviate Agents TypesScript/JavaScript client.",
+    description: "Use the official Query Agent TypeScript/JavaScript client.",
     link: "/agents/clients/typescript/",
     icon: "fab fa-js",
   }

diff --git a/docs/agents/clients/python.md b/docs/agents/clients/python.md
@@ -1,6 +1,6 @@
 ---
 title: Python client
-description: "Use the Python client to interact with Weaviate Agents."
+description: "Use the Python client to interact with the Query Agent."
 image: og/docs/agents.jpg
 tags: ['agents', 'query-agent', 'clients']
 ---
@@ -20,22 +20,22 @@ export const pythonCardsData = [
   },
 ];
 
-The Python client allows you to easily interact with the Weaviate Agents API from your Python applications. 
+The Python client allows you to easily interact with the Query Agent API from your Python applications. 
 
 It relies on the [Weaviate Client package](../../weaviate/client-libraries/python/index.mdx), and handles authentication and connection to your Weaviate instance from there.
 
 
 :::note Python client (SDK)
 
-The latest Weaviate Agents Python client is version `v||site.agents_python_version||`.
+The latest Query Agent Python client is version `v||site.agents_python_version||`.
 
 <QuickLinks items={pythonCardsData} />
 
 :::
 
 ## Installation
 
-The Weaviate Agents Python client is distributed as the [`weaviate-agents`](https://pypi.org/project/weaviate-agents/) package on PyPI, and depends on the [`weaviate-client`](https://pypi.org/project/weaviate-client/) package. You can install it in one of two equivalent ways.
+The Query Agent Python client is distributed as the [`weaviate-agents`](https://pypi.org/project/weaviate-agents/) package on PyPI, and depends on the [`weaviate-client`](https://pypi.org/project/weaviate-client/) package. You can install it in one of two equivalent ways.
 
 **Recommended: Install via the `weaviate-client` extra**
 

diff --git a/docs/agents/clients/typescript.md b/docs/agents/clients/typescript.md
@@ -1,6 +1,6 @@
 ---
 title: JavaScript/TypeScript client
-description: "Use the TypeScript client to interact with Weaviate Agents."
+description: "Use the TypeScript client to interact with the Query Agent."
 image: og/docs/agents.jpg
 tags: ['agents', 'query-agent', 'clients']
 ---
@@ -20,21 +20,21 @@ export const pythonCardsData = [
   },
 ];
 
-The TypeScript client supports code that is written in TypeScript or JavaScript. It allows you to easily interact with the Weaviate Agents API from your JavaScript or TypeScript applications.
+The TypeScript client supports code that is written in TypeScript or JavaScript. It allows you to easily interact with the Query Agent API from your JavaScript or TypeScript applications.
 
 It relies on the [Weaviate Client package](../../weaviate/client-libraries/typescript/index.mdx), and handles authentication and connection to your Weaviate instance from there.
 
-:::note JavaScript/TypeScript Client client (SDK)
+:::note JavaScript/TypeScript client (SDK)
 
-The latest Weaviate Agents TypeScript client is version `v||site.agents_typescript_version||`.
+The latest Query Agent TypeScript client is version `v||site.agents_typescript_version||`.
 
 <QuickLinks items={pythonCardsData} />
 
 :::
 
 ## Installation
 
-The Weaviate Agents TypeScript client is distributed as the [`weaviate-agents`](https://www.npmjs.com/package/weaviate-agents) package on npm, and depends on the [`weaviate-client`](https://www.npmjs.com/package/weaviate-client) package, which it declares as a peer dependency. You should install both packages together:
+The Query Agent TypeScript client is distributed as the [`weaviate-agents`](https://www.npmjs.com/package/weaviate-agents) package on npm, and depends on the [`weaviate-client`](https://www.npmjs.com/package/weaviate-client) package, which it declares as a peer dependency. You should install both packages together:
 
 ```shell
 npm install weaviate-client weaviate-agents

diff --git a/docs/agents/guides/search_mode.md b/docs/agents/guides/search_mode.md
@@ -67,6 +67,7 @@ The `.search()` method accepts several arguments:
 | `query` | The user query you want the agent to search with. This can be a simple string (`"Find me some vintage shoes under $70"`) or a list of chat messages (for conversational context). [See the page on multi-turn conversations for more detail](../reference/multi_turn_conversations.md). |
 | `collections` | 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](../reference/advanced_collections.md). |
 | `limit` | The maximum number of results returned in this page of results. Use [`.next()`](#pagination) to fetch additional pages. |
+| `filtering` | Either `"recall"` or `"precision"` to control filter generation. `"recall"` favors more results across filter interpretations; `"precision"` favors strict intent match. See [Customized filtering](#customized-filtering) below. |
 | `diversity_weight` | A value between `0.0` and `1.0` that biases the result ranking towards diversity using Maximal Marginal Relevance (MMR). See [Diversity ranking](#diversity-ranking) below. |
 
 </TabItem>
@@ -76,13 +77,42 @@ The `.search()` method accepts several arguments:
 | `query` | The user query you want the agent to search with. This can be a simple string (`"Find me some vintage shoes under $70"`) or a list of chat messages (for conversational context). [See the page on multi-turn conversations for more detail](../reference/multi_turn_conversations.md). |
 | `collections` | 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](../reference/advanced_collections.md). |
 | `limit` | The maximum number of results returned in this page of results. Use [`.next()`](#pagination) to fetch additional pages. |
+| `filtering` | Either `"recall"` or `"precision"` to control filter generation. `"recall"` favors more results across filter interpretations; `"precision"` favors strict intent match. See [Customized filtering](#customized-filtering) above. |
 | `diversityWeight` | A value between `0.0` and `1.0` that biases the result ranking towards diversity using Maximal Marginal Relevance (MMR). See [Diversity ranking](#diversity-ranking) below. |
 
 </TabItem>
 </Tabs>
 
 For more advanced searches, you can also specify _additional filters_ within the collection configuration. [See the page on additional filters for more detail](../reference/additional_filters.md).
 
+### Customized filtering
+
+Search Mode uses query rewriting to transform your original query into one or multiple Weaviate queries, each with either a search query, metadata filters, or both. The `filtering` parameter controls how many Weaviate queries are generated.
+
+- **`"recall"`** (default): Generates multiple Weaviate queries spanning different filters and interpretations of the user query. You should use these when you prefer to get results, even if they don't match every criteria in your query.
+
+- **`"precision"`**: Generates a single Weaviate query targeting the most likely interpretation of the user query. You should use this when you want the results to follow your query intent closely, even if that means potentially receiving no results.
+
+<Tabs className="code" groupId="languages">
+    <TabItem value="py_agents" label="Python">
+        <FilteredTextBlock
+            text={PyCode}
+            startMarker="# START FilteringExample"
+            endMarker="# END FilteringExample"
+            language="py"
+        />
+    </TabItem>
+    <TabItem value="ts_agents" label="JavaScript/TypeScript">
+        <FilteredTextBlock
+            text={TSCode}
+            startMarker="// START FilteringExample"
+            endMarker="// END FilteringExample"
+            language="ts"
+        />
+    </TabItem>
+
+</Tabs>
+
 ### Diversity ranking
 
 `Search` supports adding diversity weighting to result rankings using Maximal Marginal Relevance (MMR). This is enabled by passing a `diversity_weight` parameter in the range of `0.0` to `1.0` — higher values favor more varied results over the most relevant ones.
@@ -147,6 +177,10 @@ The Search Mode response has the following properties:
 
 </Tabs>
 
+:::note Result scores
+The `search_results` / `searchResults` field reuses Weaviate's native `QueryReturn` / `WeaviateReturn` type, so results have the same shape as a standard Weaviate query. However, the `score` in each object's metadata is replaced with Search Mode's own ranking score rather than the original Weaviate search score.
+:::
+
 
 ### Pagination
 

diff --git a/docs/agents/index.md b/docs/agents/index.md
@@ -151,7 +151,7 @@ Already have a cluster but no data? Upload via CSV in the cloud console, or [via
 
 
 <!-- :::info Changelog and feedback
-The official changelog for Weaviate Agents can be [found here](https://weaviateagents.featurebase.app/changelog). If you have feedback, such as feature requests, bug reports or questions, please [submit them here](https://weaviateagents.featurebase.app/), where you will be able to see the status of your feedback and vote on others' feedback.
+The official changelog for the Query Agent can be [found here](https://weaviateagents.featurebase.app/changelog). If you have feedback, such as feature requests, bug reports or questions, please [submit them here](https://weaviateagents.featurebase.app/), where you will be able to see the status of your feedback and vote on others' feedback.
 ::: -->
 
 import DocsFeedback from '/_includes/docs-feedback.mdx';

diff --git a/docs/agents/installation.md b/docs/agents/installation.md
@@ -7,6 +7,8 @@ tags: ['agents', 'query-agent', 'getting-started']
 
 <CloudOnlyBadge />
 
+Install the Query Agent client package alongside the regular Weaviate client. Below are the prerequisites and the install commands for Python and JavaScript/TypeScript.
+
 ## Prerequisites
 
 :::info What does the Query Agent have access to?
@@ -27,7 +29,7 @@ At this time, the Query Agent clients are available only for Python and JavaScri
 
 ## Python client
 
-For Python, you can install the Weaviate client library with the optional `agents` extras to use Weaviate Agents. This will install the `weaviate-agents` package along with the `weaviate-client` package. For JavaScript/TypeScript, you can install the `weaviate-agents` package alongside the `weaviate-client` package.
+For Python, you can install the Weaviate client library with the optional `agents` extras to use the Query Agent. This will install the `weaviate-agents` package along with the `weaviate-client` package. For JavaScript/TypeScript, you can install the `weaviate-agents` package alongside the `weaviate-client` package.
 
 Install the client library using the following command:
 

diff --git a/docs/agents/quickstart.md b/docs/agents/quickstart.md
@@ -13,6 +13,8 @@ import TSCode from '!!raw-loader!/docs/agents/\_includes/code/quickstart.mts';
 
 <CloudOnlyBadge />
 
+This quickstart walks through connecting to a Weaviate Cloud cluster, pointing the Query Agent at one or more existing collections, and running your first natural-language queries in both Search Mode and Ask Mode.
+
 ## Prerequisites
 
 Ensure you have access to:

diff --git a/docs/agents/recipes/index.mdx b/docs/agents/recipes/index.mdx
@@ -1,10 +1,12 @@
 ---
-title: Recipes
+title: Tutorials and guides
 description: "Examples of using the Query Agent in different use cases."
 image: og/docs/agents.jpg
 tags: ['agents', 'query-agent', 'recipes']
 ---
 
 import RecipesCards from "@site/src/components/RecipesCards";
 
+Self-contained examples that show how to apply the Query Agent to specific problems — from getting started against a single collection to wiring it into a Streamlit chat UI or exposing it as a tool to another LLM.
+
 <RecipesCards path="/agents/recipes" />
diff --git a/docs/agents/reference/additional_filters.md b/docs/agents/reference/additional_filters.md
@@ -11,8 +11,6 @@ import FilteredTextBlock from '@site/src/components/Documentation/FilteredTextBl
 import PyCode from '!!raw-loader!/docs/agents/_includes/code/additional_filters.py';
 import TSCode from '!!raw-loader!/docs/agents/_includes/code/additional_filters.mts';
 
-<!-- Details on using the `additional_filters` argument, as well as typical usecases or examples where this might be useful. -->
-
 Additional filters can be used to subset the data in a single collection manually in addition to whatever filters the Query Agent decides to use in a particular search.
 
 These persistent filters are defined at the specification of the collection, and combined with agent-generated filters using logical `AND` operations at search time.

diff --git a/docs/agents/reference/advanced_collections.md b/docs/agents/reference/advanced_collections.md
@@ -11,14 +11,6 @@ import FilteredTextBlock from '@site/src/components/Documentation/FilteredTextBl
 import PyCode from '!!raw-loader!/docs/agents/_includes/code/advanced_collections.py';
 import TSCode from '!!raw-loader!/docs/agents/_includes/code/advanced_collections.mts';
 
-<!-- Contains:
-* Explanation on how the QA can choose which collections are queried
-* Detail on how you can pass either string or `QueryAgentCollectionConfig` to the `collections` argument to `.ask()` or `.search()`
-* Full breakdown of `QueryAgentCollectionConfig` and all its arguments:
-    * `target_vector`
-    * `view_properties`
-    * `additional_filters` and link to additional filters reference page -->
-
 The Query Agent, in Ask Mode or Search Mode, has the option to search one or more of any collections that are provided to it. 
 
 These collections can either be specified by a string (the name of the collection) or via a more advanced configuration.

diff --git a/docs/agents/reference/instantiation.md b/docs/agents/reference/instantiation.md
@@ -12,6 +12,8 @@ import FilteredTextBlock from '@site/src/components/Documentation/FilteredTextBl
 import PyCode from '!!raw-loader!/docs/agents/_includes/code/instantiation.py';
 import TSCode from '!!raw-loader!/docs/agents/_includes/code/instantiation.mts';
 
+Instantiate the Query Agent against an authenticated Weaviate Cloud client. Configuration can be set at construction time (collections, system prompt, default timeout) and most options can also be overridden per call to `ask()` or `search()`.
+
 ## Basic instantiation
 
 The Query Agent requires only a target [Weaviate Cloud instance](/cloud/manage-clusters/connect.mdx) to be initialised. First, set up a Weaviate client:

diff --git a/docs/agents/reference/multi_turn_conversations.md b/docs/agents/reference/multi_turn_conversations.md
@@ -11,8 +11,6 @@ import FilteredTextBlock from '@site/src/components/Documentation/FilteredTextBl
 import PyCode from '!!raw-loader!/docs/agents/_includes/code/conversations.py';
 import TSCode from '!!raw-loader!/docs/agents/_includes/code/conversations.mts';
 
-<!-- Detail on passing user/assistant message history instead of user query, typical usecases. Maybe an example function that iteratively updates message history every time `qa.ask()` is called. -->
-
 The Query Agent transforms a natural language query into actionable searches. You can either pass a single string for the query, or provide more context by including a full conversation with previous message turns.
 
 

diff --git a/docs/agents/reference/troubleshooting.md b/docs/agents/reference/troubleshooting.md
@@ -5,6 +5,8 @@ image: og/docs/agents.jpg
 tags: ['agents', 'query-agent', 'troubleshooting']
 ---
 
+Things to check when the Query Agent isn't behaving as expected, plus the soft usage limits and typical execution timings to keep in mind.
+
 ## Usage limits
 
 import UsageLimits from "/\_includes/agents/query-agent-usage-limits.mdx";

diff --git a/docs/cloud/faq.mdx b/docs/cloud/faq.mdx
@@ -14,7 +14,7 @@ Frequently asked questions (FAQs) about [Weaviate Cloud (WCD)](/go/console?utm_c
 <details>
 <summary> Answer </summary>
 
-Using Weaviate Cloud gives you access to a 14-day free sandbox for testing. You also get access to advanced features like [Weaviate Embeddings](docs/cloud/embeddings/index.md) and [Weaviate Agents](docs/agents/index.md), which are not available in all deployment methods.
+Using Weaviate Cloud gives you access to a 14-day free sandbox for testing. You also get access to advanced features like [Weaviate Embeddings](docs/cloud/embeddings/index.md) and the [Query Agent](docs/agents/index.md), which are not available in all deployment methods.
 
 </details>