Edit

Migrate agentic retrieval code to the latest version

If you wrote agentic retrieval code using an earlier REST API version, this article explains when and how to migrate to a newer version. It also describes breaking and nonbreaking changes for all API versions that support agentic retrieval.

Migration instructions are intended to help you run an existing solution on a newer API version. The instructions in this article help you address breaking changes at the API level so that your app runs as before. For help with adding new functionality, start with What's new in Azure AI Search.

Tip

Using Azure SDKs instead of REST? Read this article to learn about breaking changes, and then install the latest package to begin your updates. Before you start, check the SDK changelogs to confirm API updates: Python, .NET, JavaScript, Java.

When to migrate

Every version that supports agentic retrieval has introduced breaking changes. You can continue to run older code unchanged by retaining the API version value, but to benefit from bug fixes, improvements, and newer functionality, you must update your code.

If your code targets a preview version, we recommend migrating to the latest stable version only if your use case is fully supported by 2026-04-01. If you rely on answer synthesis, non-minimal reasoning effort, or multi-turn messages, review breaking and nonbreaking changes before you decide to migrate. Those capabilities remain in preview.

How to migrate

  • The supported migration path is incremental. If your code targets 2025-05-01-preview, first migrate to 2025-08-01-preview, and then to 2025-11-01-preview, and so on.

  • To understand the scope of changes, review breaking and nonbreaking changes for each version.

  • "Migration" means creating new, uniquely named objects that implement the behaviors of the previous version. You can't overwrite an existing object if properties are added or deleted on the API. One advantage of creating new objects is the ability to preserve existing objects while new ones are developed and tested.

  • For each object that you migrate, start by getting the current definition from the search service so that you can review existing properties before specifying the new one.

  • Delete older versions only after your migration is fully tested and deployed.

If you're migrating from 2025-11-01-preview, you can migrate directly to 2026-04-01. Your index and content remain unchanged; only the knowledge base schema and the retrieve request shape require updates.

  1. Migrate knowledge sources
  2. Migrate the knowledge base
  3. Update the retrieve request
  4. Update billing consent
  5. Update code and clients

Migrate knowledge sources

searchIndex, azureBlob, indexedOneLake, and web knowledge source types are generally available in 2026-04-01. Other knowledge source types remain in preview.

  1. Use Knowledge Sources - Get (REST API) to get the current definition.

    GET {{search-endpoint}}/knowledge-sources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

  2. In the response, identify what to carry forward and what to remove:

    • For searchIndex and web, carry forward all property values.

    • For azureBlob and indexedOneLake, carry forward all property values, but omit ingestionPermissionOptions from ingestionParameters. This property isn't supported in 2026-04-01.

  3. Use Knowledge Sources - Create Or Update (REST API) to create a new knowledge source with a unique name, the 2026-04-01 API version, and the property values from the previous step.

    The following example shows a searchIndex knowledge source. Use a similar pattern for azureBlob, indexedOneLake, and web knowledge sources.

    PUT {{search-endpoint}}/knowledge-sources/{{new-knowledge-source-name}}?api-version=2026-04-01
api-key: {{api-key}}
Content-Type: application/json

{
  "name": "{{new-knowledge-source-name}}",
  "description": "Knowledge source backed by a search index.",
  "kind": "searchIndex",
  "searchIndexParameters": {
    "searchIndexName": "{{index-name}}",
    "sourceDataFields": [
      { "name": "id" },
      { "name": "page_chunk" },
      { "name": "page_number" }
    ]
  }
}

Migrate the knowledge base

The 2026-04-01 knowledge base has a simpler schema than the 2025-11-01-preview version: it keeps knowledgeSources and drops answer generation settings. Review the current definition before you create a new object.

  1. Use Knowledge Bases - Get (REST API) to get the current definition.

    GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

  2. In the response, identify what to carry forward and what to remove:

    • Note the knowledgeSources references. Carry these forward into the new knowledge base.

    • If present, remove outputMode, answerInstructions, and retrievalInstructions. These properties aren't supported in 2026-04-01.

    • If your knowledge base uses a web knowledge source, keep models. Web retrieval requires model-backed summarization. For all other knowledge source types, remove models.

  3. Use Knowledge Bases - Create Or Update (REST API) to create a new knowledge base with a unique name, the 2026-04-01 API version, and only the supported properties.

    PUT {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}?api-version=2026-04-01
api-key: {{api-key}}
Content-Type: application/json

{
  "name": "{{new-knowledge-base-name}}",
  "description": "Minimal knowledge base for search index retrieval.",
  "knowledgeSources": [
    { "name": "{{new-knowledge-source-name}}" }
  ]
}

Update the retrieve request

The 2026-04-01 retrieve request has a different shape than the preview version:

  • Use intents instead of messages.

  • Use maxOutputSizeInTokens instead of maxOutputSize.

  • If present, remove retrievalReasoningEffort and alwaysQuerySource. These parameters aren't supported in 2026-04-01.

  • For follow-up questions, send a new retrieve request with a new semantic intent. 2026-04-01 doesn't maintain a running messages transcript.

To test your knowledge base output with a query, use the 2026-04-01 version of Knowledge Retrieval - Retrieve (REST API).

POST {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}/retrieve?api-version=2026-04-01
api-key: {{api-key}}
Content-Type: application/json

{
  "intents": [
    {
      "type": "semantic",
      "search": "{{your-query-text}}"
    }
  ],
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "{{new-knowledge-source-name}}",
      "kind": "searchIndex",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "rerankerThreshold": 2.5
    }
  ],
  "maxRuntimeInSeconds": 30,
  "maxOutputSizeInTokens": 6000
}

If the response has a 200 OK HTTP code, your knowledge base successfully retrieved content from the knowledge source.

Starting with 2026-04-01, agentic retrieval billing consent is controlled by a dedicated knowledgeRetrieval property that's separate from semanticSearch, which now applies only to semantic ranker billing. knowledgeRetrieval is a management plane property, so you set it through the Search Management REST API, not the Search Service REST API.

Use the latest preview version of Services - Create Or Update (REST API) to set knowledgeRetrieval on your search service.

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2026-03-01-preview
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "properties": {
    "knowledgeRetrieval": "standard"
  }
}

For valid values and billing details, see Enable or disable agentic retrieval billing.

Update code and clients for 2026-04-01

To complete your migration:

  1. Update client calls to use the 2026-04-01 API version.

  2. Update any hardcoded knowledge base or knowledge source names in your code to reference the new objects created during migration.

  3. If you migrated azureBlob or indexedOneLake knowledge sources, update any code or scripts that reference the associated index, indexer, data source, or skillset by name to point to the new objects.

  4. Update code that processes retrieve responses. Responses return extractive grounding content with activity and references, not synthesized answers.

  5. Delete preview objects only after the new objects are fully validated and deployed.

Version-specific changes

This section covers breaking and nonbreaking changes for the following REST API versions:

2026-04-01

2026-04-01 is the first stable API version for agentic retrieval. It establishes a minimal, extractive retrieval contract and removes preview-era message-based query planning and answer synthesis capabilities.

To review the REST API reference documentation for this version, select the 2026-04-01 API version filter at the top of the page.

The following changes affect both the knowledge base schema and the retrieve request:

  • retrievalReasoningEffort is removed. Knowledge bases previously configured with low or medium reasoning effort aren't compatible with 2026-04-01 and must be recreated.

  • outputMode is removed. Retrieval returns extractive grounded content by default. Answer synthesis isn't supported.

The following changes affect the retrieve request only:

  • intents replaces messages.

  • alwaysQuerySource is removed from knowledgeSourceParams.

  • maxOutputSize is renamed to maxOutputSizeInTokens.

  • Conversational state isn't maintained across requests. The messages-based multi-turn pattern isn't supported.

The following change affects azureBlob and indexedOneLake knowledge sources:

  • ingestionPermissionOptions is removed from ingestionParameters. azureBlob and indexedOneLake knowledge sources that include this property must be recreated without it.

Note

Sending removed fields returns a 400 Bad Request HTTP code. The retrieve request doesn't drop or tolerate fields that no longer exist in this version.

2025-11-01-preview

To review the REST API reference documentation for this version, select the 2025-11-01-preview API version filter at the top of the page.

  • Knowledge agent is renamed to knowledge base.

    Previous route New route
    /agents /knowledgebases
    /agents/agent-name /knowledgebases/knowledge-base-name
    /agents/agent-name/retrieve /knowledgebases/knowledge-base-name/retrieve

  • Knowledge agent (base) outputConfiguration is renamed to outputMode and changed from an object to a string enumerator. Several properties are impacted:

    • includeActivity is moved from outputConfiguration onto the retrieval request object directly.
    • attemptFastPath in outputConfiguration is removed entirely. The new minimal reasoning effort is the replacement.

  • Knowledge agent (base) requestLimits is removed. Its child properties of maxRuntimeInSeconds and maxOutputSize are moved onto the retrieval request object directly.

  • Knowledge agent (base) knowledgeSources parameters now only list the names of knowledge source used by a knowledge base. Other child properties that used to be under knowledgeSources are moved to the knowledgeSourceParams properties of the retrieval request object:

    • rerankerThreshold
    • alwaysQuerySource
    • includeReferenceSourceData
    • includeReferences

    The maxSubQueries property is gone. Its replacement is the new retrieval reasoning effort property.

  • Knowledge agent (base) retrieval request object: The semanticReranker activity record is replaced with the agenticReasoning activity record type.

  • Knowledge sources for both azureBlob and searchIndex: top-level properties for identity, embeddingModel, chatCompletionModel, disableImageVerbalization, and ingestionSchedule are now part of an ingestionParameters object on the knowledge source. All knowledge sources that pull from a search index have an ingestionParameters object.

  • For searchIndex knowledge sources only: sourceDataSelect is renamed to sourceDataFields and is an array that accepts fieldName and fieldToSearch.

2025-08-01-preview

To review the REST API reference documentation for this version, select the 2025-08-01-preview API version filter at the top of the page.

  • Introduces knowledge sources as the new way to define data sources, supporting both searchIndex (one or multiple indexes) and azureBlob kinds. For more information, see Create a search index knowledge source and Create a blob knowledge source.

  • Requires knowledgeSources instead of targetIndexes in agent definitions. For migration steps, see How to migrate.

  • Removes defaultMaxDocsForReranker support. This property previously existed in targetIndexes, but there's no replacement in knowledgeSources.

2025-05-01-preview

This REST API version introduces agentic retrieval and knowledge agents. Each agent definition requires a targetIndexes array that specifies a single index and optional properties, such as defaultRerankerThreshold and defaultIncludeReferenceSourceData.

To review the REST API reference documentation for this version, select the 2025-05-01-preview API version filter at the top of the page.

Related content

  • Last updated on