Set the retrieval reasoning effort (preview)

Note

Azure AI Search is available through the Azure portal, REST APIs, and Azure SDKs. It also underpins Foundry IQ, the managed knowledge layer that transforms enterprise content into reusable, permission-aware knowledge bases for agents in the Microsoft Foundry portal.

Note

Some agentic retrieval features are generally available in the 2026-04-01 REST API. However, this feature remains in preview and requires a preview REST API. Preview features are provided without a service-level agreement and aren't recommended for production workloads. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Important

These features and functionality are part of the 2026-08-01-preview REST API. The 2026-08-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 Microsoft Azure Previews.

The 2026-08-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. For more information, see the Azure AI Search Transparency Note.

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. If neither setting is present, the service uses low.

Usage support

Azure portal	Microsoft Foundry portal	.NET SDK	Python SDK	Java SDK	JavaScript SDK	REST API
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Prerequisites

An existing knowledge base with at least one knowledge source and a model configuration.
Permission to update and query knowledge bases. Configure keyless authentication with the Search Service Contributor and Search Index Data Reader roles assigned to your user account (recommended) or use an admin API key.

The latest Azure.Search.Documents preview package: dotnet add package Azure.Search.Documents --prerelease
For keyless authentication, the Azure.Identity package: dotnet add package Azure.Identity

The latest azure-search-documents preview package: pip install --pre azure-search-documents
For keyless authentication, the azure-identity package: pip install azure-identity

The 2026-08-01-preview version of the Search Service REST API.
For keyless authentication, include a Microsoft Entra ID token in the Authorization header of each HTTP request.

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 (preview) 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 (preview) 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. 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, a high-precision semantic classifier evaluates the retrieved documents. If the initial results aren't sufficiently relevant, the service performs one follow-up iteration using a revised query plan.	Use `medium` to maximize the utility of LLM-assisted knowledge retrieval.	10,000 answer tokens. Maximum of 50 documents for semantic ranking, and 20 documents if the semantic ranker uses L3 classification. Available in select regions.
`auto`	Starts with a lightweight retrieval pass. If the first pass provides enough grounding, the service returns the result. Otherwise, it continues with LLM-based query planning, up to medium effort.	Use `auto` when you want the service to balance retrieval depth and latency for each request.	Requires the 2026-08-01-preview REST API. Requires a model on the knowledge base. Available in all regions that support agentic retrieval. Earlier API versions return `400 Bad Request`.

Iterative search for medium retrieval

A medium retrieval reasoning effort provides iterative search if initial results aren't sufficiently relevant. An extra semantic classifier model is called to determine if a second iteration is necessary.

The semantic classifier:

Recognizes when there's enough context to answer the question.
Retries on insufficient results, using existing information for context. New queries might drill down for more focused detail, or broaden the search. The activity log in the response shows the generated queries used for a more comprehensive answer.
Rescores using L3 classification. The range is identical to L2 ranking, an absolute range of zero through 4.0.

There's only one retry. Each iteration adds latency and cost, so the system constrains retry to one pass. A second iteration adds input tokens to the query pipeline, which adds to the overall billable input token count.

Iteration can reuse existing knowledge sources or choose different sources. The second pass selects the most promising knowledge source to provide the missing information.

Region support for medium retrieval

You can set a medium retrieval reasoning effort if your search service is in one of the following regions:

East US 2
East US
South Central US
West US 3
West US 2
West US
Germany West Central
North Europe
Switzerland North
Sweden Central
Spain Central
UK South
Korea Central
Japan East
Southeast Asia

Set the reasoning effort in a knowledge base

Set retrievalReasoningEffort in a knowledge base definition to establish the default for its queries. The auto reasoning effort requires a model configuration. The following example preserves the existing knowledgeSources and models configuration, sets the reasoning effort to auto, and updates the knowledge base.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;

var endpoint = new Uri("<search-endpoint>");
var credential = new DefaultAzureCredential();
var knowledgeBaseName = "<knowledge-base-name>";

var indexClient = new SearchIndexClient(endpoint, credential);
var knowledgeBase = (
    await indexClient.GetKnowledgeBaseAsync(knowledgeBaseName)).Value;
knowledgeBase.RetrievalReasoningEffort =
    new KnowledgeRetrievalAutoReasoningEffort();
await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);

Reference: KnowledgeBase

To use another level, replace KnowledgeRetrievalAutoReasoningEffort with KnowledgeRetrievalMinimalReasoningEffort, KnowledgeRetrievalLowReasoningEffort, or KnowledgeRetrievalMediumReasoningEffort.

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeRetrievalAutoReasoningEffort,
)

endpoint = "<search-endpoint>"
credential = DefaultAzureCredential()
knowledge_base_name = "<knowledge-base-name>"

index_client = SearchIndexClient(endpoint, credential)
knowledge_base = index_client.get_knowledge_base(knowledge_base_name)
knowledge_base.retrieval_reasoning_effort = (
    KnowledgeRetrievalAutoReasoningEffort()
)
index_client.create_or_update_knowledge_base(knowledge_base)

Reference: KnowledgeBase

@api-version = 2026-08-01-preview
@knowledge-base-url = {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}

PUT {{knowledge-base-url}}?api-version={{api-version}}
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "{{knowledge-base-name}}",
  "knowledgeSources": [
    {
      "name": "{{knowledge-source-name}}"
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "{{aoai-endpoint}}",
        "authIdentity": null,
        "deploymentId": "{{model-deployment-name}}",
        "modelName": "{{model-name}}"
      }
    }
  ],
  "retrievalReasoningEffort": {
    "kind": "auto"
  }
}

Reference: Knowledge Bases - Create or Update

To use another level, set retrievalReasoningEffort.kind to minimal, low, or medium.

Set the reasoning effort in a retrieve request

Set retrievalReasoningEffort in a retrieve request to override the knowledge base default for that request. The following example sends a message, uses low to override the auto default from the previous section, and enables answer synthesis (preview).

using Azure.Identity;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

var endpoint = new Uri("<search-endpoint>");
var credential = new DefaultAzureCredential();
var knowledgeBaseName = "<knowledge-base-name>";

var kbClient = new KnowledgeBaseRetrievalClient(
    endpoint, knowledgeBaseName, credential);
var request = new KnowledgeBaseRetrievalRequest
{
    RetrievalReasoningEffort =
        new KnowledgeRetrievalLowReasoningEffort(),
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis
};

request.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("What is the return policy?")
        }
    ) { Role = "user" }
);

var result = await kbClient.RetrieveAsync(request);

Reference: KnowledgeBaseRetrievalRequest

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalOutputMode,
    KnowledgeRetrievalLowReasoningEffort,
)

endpoint = "<search-endpoint>"
credential = DefaultAzureCredential()
knowledge_base_name = "<knowledge-base-name>"

kb_client = KnowledgeBaseRetrievalClient(
    endpoint,
    credential,
    knowledge_base_name=knowledge_base_name,
)
request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="What is the return policy?"
                )
            ],
        )
    ],
    retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort(),
    output_mode=KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
)

result = kb_client.retrieve(request)

Reference: KnowledgeBaseRetrievalRequest

@api-version = 2026-08-01-preview
@retrieve-url = {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}/retrieve

POST {{retrieve-url}}?api-version={{api-version}}
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the return policy?"
        }
      ]
    }
  ],
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "outputMode": "answerSynthesis"
}

Reference: Knowledge Retrieval - Retrieve

The retrieve request returns a grounded answer based on the knowledge sources configured in the knowledge base.

Povratne informacije

Je li ova stranica bila od pomoći?

Last updated on 2026-08-31