From 59318eec9ad98728f1bd6c41710c6d621266b32b Mon Sep 17 00:00:00 2001
From: Connor Shorten <connorshorten300@gmail.com>
Date: Fri, 1 May 2026 10:57:04 -0400
Subject: [PATCH] Revert "Revert "Add Docs for Suggest Queries Mode""

---
 _includes/agents/query-agent-usage-limits.mdx |  1 +
 docs/agents/_includes/query_agent.mts         | 13 ++++++++
 docs/agents/_includes/query_agent.py          | 11 +++++++
 docs/agents/query/usage.md                    | 32 ++++++++++++++++++-
 4 files changed, 56 insertions(+), 1 deletion(-)

diff --git a/_includes/agents/query-agent-usage-limits.mdx b/_includes/agents/query-agent-usage-limits.mdx
index 6f9e288e4..4162666b6 100644
--- a/_includes/agents/query-agent-usage-limits.mdx
+++ b/_includes/agents/query-agent-usage-limits.mdx
@@ -4,5 +4,6 @@ Requests are consumed based on query type:
 
 - `Ask`: 4 requests per query
 - `Search`: 1 request per query
+- `Suggest Queries`: 1 request per query
 
 This limit may change in the future. For questions about usage limits, contact [product@weaviate.io](mailto:product@weaviate.io).
diff --git a/docs/agents/_includes/query_agent.mts b/docs/agents/_includes/query_agent.mts
index 585cd2ddc..2e8e448f6 100644
--- a/docs/agents/_includes/query_agent.mts
+++ b/docs/agents/_includes/query_agent.mts
@@ -582,6 +582,19 @@ if (basicResponse.missingInformation && basicResponse.missingInformation.length
 if (!basicResponse.finalAnswer || basicResponse.finalAnswer === '') {
     throw new Error('Final answer is empty or null');
 }
+
+// START SuggestQueries
+const suggestResponse = await qa.suggestQueries({
+    collections: ["IRPAPERS"],
+    numQueries: 3,
+    instructions: "High-level themes and open-ended exploration",
+});
+
+for (const suggestedQuery of suggestResponse.queries) {
+    console.log(suggestedQuery.query);
+}
+// END SuggestQueries
+
 await client.close()
 
 }
diff --git a/docs/agents/_includes/query_agent.py b/docs/agents/_includes/query_agent.py
index e12e4bb65..c1284b181 100644
--- a/docs/agents/_includes/query_agent.py
+++ b/docs/agents/_includes/query_agent.py
@@ -674,3 +674,14 @@ async def run_streaming_query():
 
 asyncio.run(run_streaming_query())
 # END StreamAsyncResponse
+
+# START SuggestQueries
+response = qa.suggest_queries(
+    collections=["IRPAPERS"],
+    num_queries=3,
+    instructions="High-level themes and open-ended exploration",
+)
+
+for suggested_query in response.queries:
+    print(suggested_query.query)
+# END SuggestQueries
diff --git a/docs/agents/query/usage.md b/docs/agents/query/usage.md
index 44fc9d191..9d6bbe8e9 100644
--- a/docs/agents/query/usage.md
+++ b/docs/agents/query/usage.md
@@ -208,10 +208,11 @@ For usage example with the async Python client, see the [Async Python client sec
 
 ## Querying
 
-The Query Agent supports two query types:
+The Query Agent supports three query types:
 
 - [**`Search`**](#search)
 - [**`Ask`**](#ask)
+- [**`Suggest Queries`**](#suggest-queries)
 
 ### `Search`
 
@@ -469,6 +470,35 @@ The conversation history helps the Query Agent understand context from previous
 
 </Tabs>
 
+### `Suggest Queries`
+
+The Query Agent can suggest queries based on the data in your collections. This is useful for helping users discover what kinds of questions they can ask, or for generating example queries for a new dataset.
+
+You can optionally specify:
+
+- `collections`: Override the collections configured at instantiation.
+- `num_queries` (`numQueries` in TypeScript): The number of queries to suggest (default: 3).
+- `instructions`: Guide the style or focus of the suggested queries.
+
+<Tabs className="code" groupId="languages">
+    <TabItem value="py_agents" label="Python">
+        <FilteredTextBlock
+            text={PyCode}
+            startMarker="# START SuggestQueries"
+            endMarker="# END SuggestQueries"
+            language="py"
+        />
+    </TabItem>
+    <TabItem value="ts_agents" label="JavaScript/TypeScript">
+        <FilteredTextBlock
+            text={TSCode}
+            startMarker="// START SuggestQueries"
+            endMarker="// END SuggestQueries"
+            language="ts"
+        />
+    </TabItem>
+</Tabs>
+
 ## Stream responses
 
 The Query Agent can also stream responses, allowing you to receive the answer as it is being generated.