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) {

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/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>
 

diff --git a/docs/cloud/tools/query-agent.mdx b/docs/cloud/tools/query-agent.mdx
@@ -71,7 +71,7 @@ In addition to selecting one or more collections to query, you can also:
 
 ## Generate code snippets
 
-After executing a query, you can also generate a code snippet that performs the same task through one of the available Weaviate Agents client libraries, either Python or TypeScript.
+After executing a query, you can also generate a code snippet that performs the same task through one of the available Query Agent client libraries, either Python or TypeScript.
 
 <div
   style={{
@@ -135,7 +135,7 @@ The WCD Query Agent does not support multi-tenancy. In order to utilize multi-te
 
 ## Further resources
 
-- [Weaviate Agents: Query Agent](/docs/agents/index.md)
+- [Query Agent](/docs/agents/index.md)
 
 ## Support
 

diff --git a/docs/contributor-guide/weaviate-docs/development.mdx b/docs/contributor-guide/weaviate-docs/development.mdx
@@ -59,7 +59,7 @@ Always fix any build errors before submitting changes, as broken builds will pre
 
 <!-- Within /agents section -->
 
-[Weaviate Agents](../index.md)
+[Query Agent](../index.md)
 ```
 
 ### Absolute link paths
@@ -69,7 +69,7 @@ Always fix any build errors before submitting changes, as broken builds will pre
 ```markdown
 <!-- Linking from /weaviate to /agents -->
 
-[Weaviate Agents](/agents/index.md)
+[Query Agent](/agents/index.md)
 
 <!-- Linking from /agents to /weaviate -->
 
@@ -83,7 +83,7 @@ Always fix any build errors before submitting changes, as broken builds will pre
 ```markdown
 <!-- Linking from _includes/ to /agents -->
 
-[Weaviate Agents](/agents/qeuery)
+[Query Agent](/agents/quickstart)
 ```
 
 This convention ensures links work correctly regardless of where the component is imported.

diff --git a/docs/contributor-guide/weaviate-docs/style-guide.mdx b/docs/contributor-guide/weaviate-docs/style-guide.mdx
@@ -48,7 +48,7 @@ The documentation is organized into key sections. When contributing, understand
 
 - **Deployment docs - `/docs/deploy`:** Documentation for deploying and operating Weaviate instances. Covers installation methods including Docker and Kubernetes, configuration options for authentication and performance, production deployment patterns, scaling and high availability setups, cloud provider-specific guides, troubleshooting information, and version migration procedures.
 
-- **Weaviate Agents - `/docs/agents`:** Documentation for Weaviate's agent framework. Includes setup instructions, usage examples, and implementation patterns for building AI agents that can interact with Weaviate databases.
+- **Query Agent - `/docs/agents`:** Documentation for the Query Agent — Weaviate's pre-built agentic search service. Includes setup instructions, mode usage (Ask, Search, Suggest Queries), configuration references, client library guides, and recipes for common patterns.
 
 - **Weaviate Cloud - `/docs/cloud`:** Documentation for Weaviate's managed cloud service. Contains account setup procedures, Weaviate embeddings service documentation, billing and subscription management, service limitations, and cloud-specific configuration options.
 

diff --git a/docs/weaviate/best-practices/code-generation.md b/docs/weaviate/best-practices/code-generation.md
@@ -98,11 +98,11 @@ Some AI-powered code generation tools such as Cursor allow you to index further
 
 Review the documentation of your specific IDE to see if it has this feature, and how to use it.
 
-### Consider using Weaviate Agents
+### Consider using the Query Agent
 
-[Weaviate Agents](/agents) are pre-built agentic services designed for searching your data, with AI deciding the search terms, filters, sorts, and other search parameters. The [Query Agent](/agents/guides/index.md) is purpose-built for this usecase.
+The [Query Agent](/agents) is a pre-built agentic search service that decides the search terms, filters, sorts, and other search parameters for you — the [modes overview](/agents/guides/index.md) covers what it can do.
 
-Weaviate agents are available for Weaviate Cloud users to enable interacting with the Weaviate Cloud instance using natural language. For some use cases, this may be a better approach than using AI-powered code generation tools.
+The Query Agent is available to Weaviate Cloud users for interacting with their Weaviate Cloud instance in natural language. For some use cases, this may be a better approach than using AI-powered code generation tools.
 
 ## Help us improve this page
 

diff --git a/docs/weaviate/client-libraries/python/index.mdx b/docs/weaviate/client-libraries/python/index.mdx
@@ -78,9 +78,9 @@ ports:
 
 </details>
 
-#### Weaviate Agents
+#### Query Agent
 
-You can install the Weaviate client library with the optional agents extras to use [Weaviate Agents](../../../agents/index.md). Install the client library using the following command:
+You can install the Weaviate client library with the optional `agents` extras to use the [Query Agent](../../../agents/index.md). Install the client library using the following command:
 
 ```bash
 pip install -U "weaviate-client[agents]"

diff --git a/docs/weaviate/config-refs/collections.mdx b/docs/weaviate/config-refs/collections.mdx
@@ -162,7 +162,7 @@ import InitialCaps from "/_includes/schemas/initial-capitalization.md";
 
 #### `description`
 
-A description of the collection. This is for your reference and can also provide additional information to [Weaviate Agents](/docs/agents/index.md).
+A description of the collection. This is for your reference and can also provide additional information to the [Query Agent](/docs/agents/index.md).
 
 ---
 

diff --git a/docs/weaviate/index.mdx b/docs/weaviate/index.mdx
@@ -125,7 +125,7 @@ As shown in the high-level overview above, the ecosystem consists of:
 
 - **[Weaviate Database](#what-is-weaviate)**: An open source vector database that stores both objects and vectors.
 - **[Weaviate Cloud](/cloud)**: A fully managed cloud deployment of the Weaviate vector database.
-- **[Weaviate Agents](/agents)**: Pre-built agentic services for Weaviate Cloud users.
+- **[Query Agent](/agents)**: A pre-built agentic search service for Weaviate Cloud users.
 - **[Weaviate Embeddings](/cloud/embeddings)**: A managed embedding inference service for Weaviate Cloud users.
 - **[External model providers](/weaviate/model-providers)**: Third-party models that integrate with Weaviate.
-Original file line number
+Diff line change
@@ Expand Up @@
     #### `description`
-    A description of the collection. This is for your reference and can also provide additional information to [Weaviate Agents](/docs/agents/index.md).
+    A description of the collection. This is for your reference and can also provide additional information to the [Query Agent](/docs/agents/index.md).
     ---
@@ Expand Down @@