Set the retrieval reasoning effort (preview)

Note

Some agentic retrieval features are generally available in the 2026-04-01 REST API version. However, this feature remains in preview and requires a preview REST API version. Preview features are provided without a service-level agreement and aren't recommended for production workloads.

Important

These features and functionality are part of the 2026-05-01-preview REST API. The 2026-05-01-preview is licensed to you as part of your Azure subscription and is subject to the terms applicable to "Previews" in the Microsoft Product Terms, the Microsoft Products and Services Data Protection Addendum ("DPA"), and the Supplemental Terms of Use for Azure Previews.

The 2026-05-01-preview supports connections to other Microsoft services and third-party services. Use of these services is subject to their respective terms and might result in data processing or storage outside of the Azure compliance boundary, as well as data flowing into the Azure compliance boundary.

It's your responsibility to manage whether your data will flow outside of your organization's compliance and geographic boundaries and any related implications, and that appropriate permissions, boundaries, and approvals are provisioned.

You're responsible for carefully reviewing and testing applications you build in the context of your specific use cases and making all appropriate decisions and customizations. This includes implementing your own responsible AI mitigations, such as metaprompts, content filters, or other safety systems, and ensuring your applications meet appropriate quality, reliability, security, and trustworthiness standards.

In agentic retrieval, you can specify the level of large language model (LLM) processing for query planning and answer formulation. Use the retrieval reasoning effort (preview) to set LLM processing levels that affect costs and latency. Extra LLM processing improves relevance, but it also takes longer and uses billable LLM resources.

You can set this property in a knowledge base or a retrieve request. The knowledge base setting establishes the default for all queries, while the retrieve request setting overrides the default on a query-by-query basis.

Prerequisites

An Azure AI Search service with a knowledge base.
Permissions to update knowledge bases. Configure keyless authentication with the Search Service Contributor role assigned to your user account (recommended) or use an API key.
If the knowledge base specifies an LLM, the search service must have a managed identity with Cognitive Services User permissions on the Azure AI services resource.
The 2026-05-01-preview REST API or an equivalent Azure SDK preview package: .NET | Java | JavaScript | Python

Choose a reasoning effort

Choose a reasoning effort based on the tradeoff you want between latency, cost, and retrieval depth.

Reasoning effort levels

Level	Description	Recommendation	Limits
`minimal`	Disables LLM-based query planning to deliver the lowest cost and latency for agentic retrieval. It issues direct text and vector searches across the knowledge sources listed in the knowledge base, and returns the best-matching passages. Because all knowledge sources in the knowledge base are always searched and no query expansion is performed, behavior is predictable and easy to control. It also means the `alwaysQueryKnowledgeSource` property on a retrieve request is ignored.	Use `minimal` for migrations from the Search API or when you want to manage query planning yourself.	`outputMode` must be set to `extractiveData`. Answer synthesis and web knowledge aren't supported. Maximum of 10 knowledge sources per knowledge base.
`low`	The default mode of agentic retrieval, running a single pass of LLM-based query planning and knowledge source selection. The agentic retrieval engine generates subqueries and fans them out to the selected knowledge sources, then merges the results. You can enable answer synthesis to produce a grounded natural-language response with inline citations.	Use `low` when you want a balance between minimal latency and deeper processing.	5,000 answer tokens. In the 2026-05-01-preview, maximum of 10 knowledge sources per knowledge base on most paid tiers. In earlier preview API versions, maximum of three subqueries from three knowledge sources per knowledge base. Maximum of 50 documents for semantic ranking, and 10 documents if the semantic ranker uses L3 classification.
`medium`	Adds deeper search and an enhanced retrieval stack to agentic retrieval to maximize completeness. After the first search is performed, a high-precision semantic classifier evaluates the retrieved documents to determine whether further processing and L3 ranking is required. If the initial results from the first pass are insufficiently relevant to the query, a follow-up iteration is performed using a revised query plan. This revised query plan takes the previous results into account and iterates by fine-tuning queries, broadening terms, or adding other knowledge sources such as the web. It also increases resource limits compared to low and minimal effort. This reasoning level optimizes for relevance rather than exhaustive recall.	Use `medium` to maximize the utility of LLM-assisted knowledge retrieval.	10,000 answer tokens. In the 2026-05-01-preview, maximum of 10 knowledge sources per knowledge base on most paid tiers. In earlier preview API versions, maximum of five subqueries from five knowledge sources per knowledge base. Maximum of 50 documents for semantic ranking, and 20 documents if the semantic ranker uses L3 classification. Available in select regions.

Set the reasoning effort in a knowledge base

This section demonstrates how to set the retrieval reasoning effort in an existing knowledge base. Although you can use this configuration for new knowledge bases, knowledge base creation is beyond the scope of this article.

To establish the default behavior, set retrievalReasoningEffort in the knowledge base definition.

### Set retrieval reasoning effort in a knowledge base
PUT {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2026-05-01-preview
Content-Type: application/json
api-key: {{api-key}}

{
  "name": "{{knowledge-base-name}}",
  "knowledgeSources": [ ... // OMITTED FOR BREVITY ],
  "retrievalReasoningEffort": {
    "kind": "low"
  }
}

Reference: Knowledge Bases - Create or Update

Set the reasoning effort in a retrieve request

To override the default on a query-by-query basis, set retrievalReasoningEffort in the retrieve request body.

### Override retrieval reasoning effort in a retrieve request
POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-05-01-preview
Content-Type: application/json
api-key: {{api-key}}

{
  "messages": [ ... // OMITTED FOR BREVITY ],
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "outputMode": "answerSynthesis",
  "maxRuntimeInSeconds": 30,
  "maxOutputSize": 6000
}

Reference: Knowledge Retrieval - Retrieve

Last updated on 2026-06-30