diff --git a/docs/query-agent/_includes/code/search_mode.mts b/docs/query-agent/_includes/code/search_mode.mts
index fc9f355b..af2bbefb 100644
--- a/docs/query-agent/_includes/code/search_mode.mts
+++ b/docs/query-agent/_includes/code/search_mode.mts
@@ -102,4 +102,15 @@ for (const obj of filteringResponse.searchResults.objects) {
}
// END FilteringExample
+// START EffortExample
+const effortResponse = await qa.search("What are Setwise Rerankers?", {
+ limit: 10,
+ effort: "high",
+});
+
+for (const obj of effortResponse.searchResults.objects) {
+ console.log(obj.properties);
+}
+// END EffortExample
+
await client.close();
diff --git a/docs/query-agent/_includes/code/search_mode.py b/docs/query-agent/_includes/code/search_mode.py
index d1bab68d..c8576661 100644
--- a/docs/query-agent/_includes/code/search_mode.py
+++ b/docs/query-agent/_includes/code/search_mode.py
@@ -107,6 +107,17 @@
print(f"Product: {obj.properties['name']} - ${obj.properties['price']}")
# END FilteringExample
+# START EffortExample
+search_response = qa.search(
+ "What are Setwise Rerankers?",
+ limit=10,
+ effort="high",
+)
+
+for obj in search_response.search_results.objects:
+ print(obj.properties)
+# END EffortExample
+
# --- 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/query-agent/guides/search_mode.md b/docs/query-agent/guides/search_mode.md
index ff4d6a24..005af083 100644
--- a/docs/query-agent/guides/search_mode.md
+++ b/docs/query-agent/guides/search_mode.md
@@ -13,7 +13,7 @@ import TSCode from '!!raw-loader!/docs/query-agent/_includes/code/search_mode.mt
-Search Mode transforms your query into actionable searches and returns the matching Weaviate objects directly — without generating an LLM-authored answer.
+Search Mode combines AI-powered semantic search with structured filtering and returns the matching Weaviate objects directly.
For example, you could ask:
@@ -21,6 +21,14 @@ For example, you could ask:
And the agent will perform semantic search for `vintage shoes`, apply a filter for `price < 70`, and return the matching objects from your collections, ready for you to render or post-process.
+You could also ask:
+
+> "Something comfortable to wear on a long flight"
+
+And the agent will use AI-powered search to find relevant objects, even when terms like `comfortable` or `long flight` never appear in your data.
+
+Under the hood, Search Mode does more than embed your query as-is. The agent writes one or more optimized semantic and structured queries, executes them against your collections, and reranks the retrieved objects by how well each one matches your original request.
+
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.search) or [the Typescript Client](https://weaviate.github.io/agents-typescript-client/classes/QueryAgent.html#search).
## Usage
@@ -69,6 +77,7 @@ The `.search()` method accepts several arguments:
| `limit` | `int` | The maximum number of results returned in this page of results. Defaults to `20`. Use [`.next()`](#pagination) to fetch additional pages. |
| `filtering` | `Literal["recall", "precision"]` | 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` | `float \| None` | 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. |
+| `effort` | `Literal["low", "medium", "high"] \| None` | The amount of effort the agent puts into the search. Higher effort may improve result quality at the expense of increased latency and cost. See [Effort](#effort) below. |
@@ -79,12 +88,36 @@ The `.search()` method accepts several arguments:
| `limit` | `number` | The maximum number of results returned in this page of results. Defaults to `20`. Use [`.next()`](#pagination) to fetch additional pages. |
| `filtering` | `"recall" \| "precision"` | 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. |
| `diversityWeight` | `number` | 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. |
+| `effort` | `"low" \| "medium" \| "high"` | The amount of effort the agent puts into the search. Higher effort may improve result quality at the expense of increased latency and cost. See [Effort](#effort) below. |
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).
+### Effort
+
+The optional `effort` parameter controls the amount of effort the agent puts into the search. It accepts one of `"low"`, `"medium"`, or `"high"`. Higher effort may improve result quality at the expense of increased latency and cost.
+
+
+
+
+
+
+
+
+
+
### 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.