Uredi

Migrate agentic retrieval code to the latest version

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.

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.

If your agentic retrieval code targets an earlier 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 an Azure SDK instead of REST? Before you upgrade the package and apply the relevant migration changes, check the changelog for your SDK language to confirm support for your target API version.

When to migrate

Most versions that support agentic retrieval 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.

Before you migrate

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

  • The supported migration path is incremental. If your code targets 2025-05-01-preview, first migrate to 2025-08-01-preview, then continue through each subsequent version until you reach your target version.

  • For a side-by-side migration, create uniquely named objects that implement the behaviors of the previous version. This approach preserves existing objects while you develop and test replacements. If an object supports update in place, the version-specific steps call out that option.

  • 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.

How to migrate

This section covers migration steps for the following API versions:

2026-08-01-preview

If you're migrating from 2026-05-01-preview, you can move directly to 2026-08-01-preview. This migration requires updates to Work IQ knowledge sources, list paging, response processing, MCP server tools, and affected generated-client calls.

  1. Migrate Work IQ knowledge sources
  2. Update list paging
  3. Update retrieve response processing
  4. Update code and clients

Migrate Work IQ knowledge sources

To migrate a Work IQ knowledge source to the new authentication configuration:

  1. Export its current definition.

  2. Update the existing knowledge source by using Knowledge Sources - Create Or Update, or create a replacement with a unique name for a side-by-side migration.

  3. Use the 2026-08-01-preview API version and configure workIQParameters.entraAppAuthentication. The applicationId and federatedCredentialId properties are required. The tenantId property is optional and defaults to the search service's tenant.

  4. If you created a replacement, update each knowledge base that references the previous knowledge source to use the replacement name.

  5. Update retrieve requests to pass the user assertion in the x-ms-query-work-iq-source-authorization header.

For setup and examples, see Create a Work IQ knowledge source (preview).

Update list paging

To replace offset-based paging with cursor-based paging:

  1. Remove $top, $skip, and $count from knowledge source list requests. Set pageSize from 1 through 3,000 to control the page size. If you omit it, the service chooses the page size.

  2. To filter by name, set search and searchType. The only supported searchType value is prefix, which is also the default. The following request returns up to 100 knowledge sources whose names start with contoso.

    GET {{search-endpoint}}/knowledgesources?api-version=2026-08-01-preview&pageSize=100&search=contoso&searchType=prefix
Authorization: Bearer {{search-access-token}}

    Reference: Knowledge Sources - List

  3. If the response contains @odata.nextLink, send that URL exactly as returned. Don't parse or modify its continuation state.

Update retrieve response processing

To process the new Work IQ reference and model-backed activity shapes:

  1. Remove dependencies on attributions, WorkIQAttribution, and seeMoreWebUrl. Read sensitivity-label metadata from searchSensitivityLabelInfo on the Work IQ reference.

  2. In query-planning, answer-synthesis, and web-summarization activity records, read modelName and deploymentId from the nested model object. The nested object and both properties are optional.

The following fragments show the response-shape changes.

{
  "references": [
    {
      "type": "workIQ",
      "id": "<reference-id>",
      "activitySource": 1,
      "sourceData": {},
      "attributions": [
        {
          "seeMoreWebUrl": "<attribution-url>"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "modelAnswerSynthesis",
      "id": 2,
      "modelName": "<model-name>"
    }
  ]
}

In 2026-08-01-preview, the same fragments use the following shape:

{
  "references": [
    {
      "type": "workIQ",
      "id": "<reference-id>",
      "activitySource": 1,
      "sourceData": {},
      "searchSensitivityLabelInfo": {
        "displayName": "<label-name>",
        "sensitivityLabelId": "<label-id>"
      }
    }
  ],
  "activity": [
    {
      "type": "modelAnswerSynthesis",
      "id": 2,
      "model": {
        "modelName": "<model-name>",
        "deploymentId": "<deployment-id>"
      }
    }
  ]
}

Update code and clients for 2026-08-01-preview

To complete your migration:

  1. On each MCP server tools item, replace inclusionMode with resultsProcessing. Map reranked to rerank and always to none. The rerank value is the default. The none value bypasses reranking and preserves the tool's underlying result order. For setup, see Configure tools for an MCP server knowledge source.

  2. If you use an Azure SDK, install a package that supports 2026-08-01-preview, and review positional list calls for parameter-order changes. REST callers aren't affected because HTTP parameters are keyed by name. In C#, prefer named arguments, such as GetKnowledgeSourcesAsync(search: ..., pageSize: ...). In Python, pass list options as keyword arguments.

  3. Test Work IQ authentication and references, cursor paging, activity-record deserialization, MCP server result ordering, and generated-client calls before you update production.

  4. If you created replacement Work IQ knowledge sources, delete the earlier sources only after the migration passes all tests, your updated application is deployed, and no knowledge base references the earlier names.

2026-05-01-preview

If you're migrating from 2026-04-01 or 2025-11-01-preview, you can move directly to 2026-05-01-preview. Requests, responses, and persisted objects from those versions remain compatible. The differences are additive features and language SDK renames.

  1. Update the API version to 2026-05-01-preview on REST requests. SDK clients use the package's default API version, so you don't need to pass an explicit serviceVersion argument. Instead, upgrade to the 2026-05-01-preview SDK package.

  2. If you use the Python or JavaScript SDK, update the retrieve client to KnowledgeBaseRetrievalClient and call retrieve(...) instead of the legacy retrieveKnowledge(...). For the full SDK shape mapping, see Update code and clients for 2026-05-01-preview.

  3. (Optional) Adopt the new 2026-05-01-preview features, such as freshness-aware retrieval, per-source and final-result document caps, persisted retrieve defaults, knowledge base CORS, and Purview sensitivity-label metadata in retrieve responses. None of these features are required to keep an existing solution working.

Update code and clients for 2026-05-01-preview

The 2026-05-01-preview SDKs introduce code-shape changes across the supported languages:

Language Migration updates
Python Create the retrieve client as KnowledgeBaseRetrievalClient(endpoint=..., credential=..., knowledge_base_name=...). Construct reasoning effort instances such as KnowledgeRetrievalLowReasoningEffort() and pass the string output_mode="answerSynthesis" on the knowledge base or retrieve request. Pass AzureOpenAIVectorizerParameters(resource_url=...) (renamed from resource_uri), using the resource root endpoint rather than an /openai/v1 endpoint.
.NET Create the retrieve client as new KnowledgeBaseRetrievalClient(endpoint, knowledgeBaseName, credential) and pass an AzureKeyCredential or token credential. To attach a key-based Azure OpenAI model to a knowledge base, set the model API key on AzureOpenAIVectorizerParameters.ApiKey.
Java Use KnowledgeBaseRetrievalClientBuilder to create the retrieve client and read results as KnowledgeBaseRetrievalResult. KnowledgeBaseRetrievalOptions now exposes setMessages(...) alongside setIntents(...), plus setRetrievalReasoningEffort, setOutputMode, setMaxOutputSize, and setMaxOutputDocuments, so message-based retrieve and answer synthesis work without a semantic-intent workaround. KnowledgeBase adds setOutputMode, setRetrievalReasoningEffort, setRetrievalInstructions, setAnswerInstructions, and setCorsOptions. SearchIndexKnowledgeSourceParams adds setAlwaysQuerySource, setFailOnError, setMaxOutputDocuments, and setEnableImageServing.
JavaScript and TypeScript Use KnowledgeRetrievalClient.retrieve({ intents: [{ type: "semantic", search: query }] }). The previous retrieveKnowledge(...) method is removed in favor of retrieve(...).

After you update the client shapes, run the full flow that creates the index, uploads documents, creates a knowledge source, creates a knowledge base, issues a retrieve request, and cleans up resources to confirm the migration end to end.

2026-04-01

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

  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

In 2026-04-01, the searchIndex, azureBlob, indexedOneLake, and web knowledge source types are generally available. 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
Authorization: Bearer {{search-access-token}}
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
Authorization: Bearer {{search-access-token}}
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
Authorization: Bearer {{search-access-token}}
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
Authorization: Bearer {{search-access-token}}
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
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "intents": [
    {
      "type": "semantic",
      "search": "{{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 the 2026-04-01 API version, 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/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2026-03-01-preview
Content-Type: application/json
Authorization: Bearer {{management-access-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.

2025-11-01-preview

If you're migrating from 2025-08-01-preview, "knowledge agent" is renamed to "knowledge base," and multiple properties are relocated to different objects and levels within an object definition.

  1. Update searchIndex knowledge sources
  2. Update azureBlob knowledge sources
  3. Replace knowledge agent with knowledge base
  4. Update the retrieve request and send a query to test your updates
  5. Update client code

Update a searchIndex knowledge source

This procedure creates a new 2025-11-01-preview searchIndex knowledge source at the same functional level as the previous 2025-08-01 version. The underlying index itself requires no updates.

  1. List all knowledge sources by name to find your knowledge source.

    ### List all knowledge sources by name
GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

  2. Get the current definition to review existing properties.

    ### Get a specific knowledge source
GET {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

    The response should be similar to the following example.

    {
     "name": "search-index-ks",
     "kind": "searchIndex",
     "description": "This knowledge source pulls from a search index created using the 2025-08-01-preview.",
     "encryptionKey": null,
     "searchIndexParameters": {
     "searchIndexName": "earth-at-night-idx",
     "sourceDataSelect": "id, page_chunk, page_number"
     },
     "azureBlobParameters": null
}

  3. Formulate a Create Knowledge Source request as the basis for your migration.

    Start with the 08-01-preview JSON.

    POST {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "search-index-ks",
    "kind": "searchIndex",
    "description": "A sample search index knowledge source",
    "encryptionKey": null,
    "searchIndexParameters": {
        "searchIndexName": "my-search-index",
        "sourceDataSelect": "id, page_chunk, page_number"
  }
}

    Make the following updates for a 2025-11-01-preview migration:

    • Give the knowledge source a new name.

    • Change the API version to 2025-11-01-preview.

    • Rename sourceDataSelect to sourceDataFields and change the string to an array with name-value pairs for each retrievable field you want to query. These are the fields to return in the search results, similar to a select clause in a classic query.

  4. Review your updates and then send the request to create the object.

    PUT {{search-endpoint}}/knowledge-sources/search-index-ks-11-01?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "search-index-ks-11-01",
    "kind": "searchIndex",
    "description": "knowledge source migrated to 2025-11-01-preview",
    "encryptionKey": null,
    "searchIndexParameters": {
        "searchIndexName": "my-search-index",
        "sourceDataFields": [
            { "name": "id" }, { "name": "page_chunk" }, { "name": "page_number" }
        ]
    }
}

You now have a migrated searchIndex knowledge source that's backward compatible with the previous version, using the correct property specifications for the 2025-11-01-preview.

The response includes the full definition of the new object. For more information about new properties available to this knowledge source type, which you can now do through updates, see How to create a search index knowledge source.

Update an azureBlob knowledge source

This procedure creates a new 2025-11-01-preview azureBlob knowledge source at the same functional level as the previous 2025-08-01 version. It creates a new set of generated objects: data source, skillset, indexer, index.

  1. List all knowledge sources by name to find your knowledge source.

    ### List all knowledge sources by name
GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

  2. Get the current definition to review existing properties.

    ### Get a specific knowledge source
GET {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

    If your workflow includes a model, the response should be similar to the following example. Notice that a response includes the names of the generated objects. These objects are fully independent of the knowledge source and remain operational even if you update or delete their knowledge source.

     {
   "name": "azure-blob-ks",
   "kind": "azureBlob",
   "description": "A sample azure blob knowledge source.",
   "encryptionKey": null,
   "searchIndexParameters": null,
   "azureBlobParameters": {
     "connectionString": "<redacted>",
     "containerName": "blobcontainer",
     "folderPath": null,
     "disableImageVerbalization": false,
     "identity": null,
     "embeddingModel": {
       "name": "embedding-model",
       "kind": "azureOpenAI",
       "azureOpenAIParameters": {
         "resourceUri": "<redacted>",
         "deploymentId": "text-embedding-3-large",
         "apiKey": "<redacted>",
         "modelName": "text-embedding-3-large",
         "authIdentity": null
       },
       "customWebApiParameters": null,
       "aiServicesVisionParameters": null,
       "amlParameters": null
     },
     "chatCompletionModel": {
       "kind": "azureOpenAI",
       "azureOpenAIParameters": {
         "resourceUri": "<redacted>",
         "deploymentId": "gpt-4o-mini",
         "apiKey": "<redacted>",
         "modelName": "gpt-4o-mini",
         "authIdentity": null
       }
 },
     "ingestionSchedule": null,
     "createdResources": {
       "datasource": "azure-blob-ks-datasource",
       "indexer": "azure-blob-ks-indexer",
       "skillset": "azure-blob-ks-skillset",
       "index": "azure-blob-ks-index"
     }
   }
 }

  3. Formulate a Create Knowledge Source request as the basis for your migration.

    Start with the 08-01-preview JSON.

    POST {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source.",
    "encryptionKey": null,
    "azureBlobParameters": {
        "connectionString": "<redacted>",
        "containerName": "blobcontainer",
        "folderPath": null,
        "disableImageVerbalization": false,
        "identity": null,
        "embeddingModel": {
            "name": "embedding-model",
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
            "resourceUri": "<redacted>",
            "deploymentId": "text-embedding-3-large",
            "apiKey": "<redacted>",
            "modelName": "text-embedding-3-large",
            "authIdentity": null
            },
            "customWebApiParameters": null,
            "aiServicesVisionParameters": null,
            "amlParameters": null
        },
        "chatCompletionModel": null,
        "ingestionSchedule": null
  }
}

    Make the following updates for a 2025-11-01-preview migration:

    • Give the knowledge source a new name.

    • Change the API version to 2025-11-01-preview.

    • Add ingestionParameters as a container for the following child properties: "embeddingModel", "chatCompletionModel", "ingestionSchedule", "contentExtractionMode".

  4. Review your updates and then send the request to create the object. New generated objects are created for the indexer pipeline.

    PUT {{search-endpoint}}/knowledge-sources/azure-blob-ks-11-01?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "encryptionKey": null,
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "ingestionParameters": {
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": false,
            "ingestionSchedule": null,
            "contentExtractionMode": "minimal"
        }
    }
}

You now have a migrated azureBlob knowledge source that's backward compatible with the previous version, using the correct property specifications for the 2025-11-01-preview.

The response includes the full definition of the new object. For more information about new properties available to this knowledge source type, which you can now do through updates, see Create a blob knowledge source.

Replace knowledge agent with knowledge base

  1. Knowledge bases require a knowledge source. Ensure you have a knowledge source that targets 2025-11-01-preview before you start.

  2. Get the current definition to review existing properties.

    ### Get a knowledge agent by name
GET {{search-endpoint}}/agents/earth-at-night?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

    The response should be similar to the following example.

    {
  "name": "earth-at-night",
  "description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.",
  "retrievalInstructions": null,
  "requestLimits": null,
  "encryptionKey": null,
  "knowledgeSources": [
    {
      "name": "earth-at-night",
      "alwaysQuerySource": null,
      "includeReferences": null,
      "includeReferenceSourceData": null,
      "maxSubQueries": null,
      "rerankerThreshold": 2.5
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "<redacted>",
        "deploymentId": "gpt-5-mini",
        "apiKey": "<redacted>",
        "modelName": "gpt-5-mini",
        "authIdentity": null
      }
    }
  ],
  "outputConfiguration": {
    "modality": "answerSynthesis",
    "answerInstructions": null,
    "attemptFastPath": false,
    "includeActivity": null
  }
}

  3. Formulate a Create Knowledge Base request as the basis for your migration.

    Start with the 08-01-preview JSON.

    PUT {{search-endpoint}}/knowledgebases/earth-at-night?api-version=2025-08-01-preview  HTTP/1.1
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "earth-at-night",
    "description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.",
    "retrievalInstructions": null,
    "encryptionKey": null,
    "knowledgeSources": [
        {
          "name": "earth-at-night",
          "alwaysQuerySource": null,
          "includeReferences": null,
          "includeReferenceSourceData": null,
          "maxSubQueries": null,
          "rerankerThreshold": 2.5
        }
    ],
    "models": [
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "<redacted>",
                "apiKey": "<redacted>",
                "deploymentId": "gpt-5-mini",
                "modelName": "gpt-5-mini"
            }
        }
    ],
    "outputConfiguration": {
        "modality": "answerSynthesis"
    }
}

    Make the following updates for a 2025-11-01-preview migration:

    • Replace the endpoint: /knowledgebases/{{knowledge-base-name}}. Give the knowledge base a unique name.

    • Change the API version to 2025-11-01-preview.

    • Delete requestLimits. The maxRuntimeInSeconds and maxOutputSize properties are now specified on the retrieve request directly.

    • Update knowledgeSources:

    • Move alwaysQuerySource, includeReferenceSourceData, includeReferences, and rerankerThreshold to the knowledgeSourceParams section of a retrieve action.

    • No changes for models.

    • Update outputConfiguration:

      • Replace outputConfiguration with outputMode.

      • Delete attemptFastPath. It no longer exists. Equivalent behavior is implemented through retrievalReasoningEffort set to minimum (see Set the retrieval reasoning effort (preview)).

      • If modality is set to answerSynthesis, make sure you set the retrieval reasoning effort to low (default) or medium.

    • Add ingestionParameters as a requirement for creating a 2025-11-01-preview azureBlob knowledge source.

  4. Review your updates and then send the request to create the object. New generated objects are created for the indexer pipeline.

     PUT {{search-endpoint}}/knowledgebases/earth-at-night-11-01?api-version={{api-version}}
 Authorization: Bearer {{search-access-token}}
 Content-Type: application/json

 {
   "name": "earth-at-night-11-01",
   "description": "A sample knowledge base at the same functional level as the previous knowledge agent.",
   "retrievalInstructions": null,
   "encryptionKey": null,
   "knowledgeSources": [
     {
         "name": "earth-at-night-ks"
     }
   ],
   "models": [
     {
       "kind": "azureOpenAI",
       "azureOpenAIParameters": {
           "resourceUri": "<redacted>",
           "apiKey": "<redacted>",
           "deploymentId": "gpt-5-mini",
           "modelName": "gpt-5-mini"
         }
     }
   ],
   "retrievalReasoningEffort": null,
   "outputMode": "answerSynthesis",
   "answerInstructions": "Provide a concise and accurate answer based on the retrieved information."
 }

You now have a knowledge base instead of a knowledge agent, and the object is backward compatible with the previous version.

The response includes the full definition of the new object. For more information about new properties available to a knowledge base, which you can now do through updates, see How to create a knowledge base.

Update and test the retrieval for 2025-11-01-preview updates

The retrieve request is modified for the 2025-11-01-preview to support more shapes, including a simpler request that minimizes LLM processing. For more information about retrieval in this preview, see Retrieve data using a knowledge base. This section explains how to update your code.

  1. Change the /agents/retrieve endpoint to /knowledgebases/retrieve.

  2. Change the API version to 2025-11-01-preview.

  3. No changes to messages are required if you're using low or medium retrieval reasoning effort. Replace messages with intents if you use minimal reasoning (see Set the retrieval reasoning effort (preview)).

  4. Modify knowledgeSourceParams to include any properties that were removed from the agent: rerankerThreshold, alwaysQuerySource, includeReferenceSourceData, includeReferences.

  5. Add retrievalReasoningEffort set to minimum if you were using attemptFastPath. If you were using maxSubQueries, it no longer exists. Use the retrievalReasoningEffort setting to specify subquery processing (see Set the retrieval reasoning effort (preview)).

To test your knowledge base's output with a query, use the 2025-11-01-preview of Knowledge Retrieval - Retrieve (REST API).

### Send a query to the knowledge base
POST {{search-endpoint}}/knowledgebases/earth-at-night-11-01/retrieve?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What are some light sources on the ocean at night" }
            ]
        }
    ],
    "includeActivity": true,
    "retrievalReasoningEffort": { "kind": "medium" },
    "outputMode": "answerSynthesis",
    "maxRuntimeInSeconds": 30,
    "maxOutputSize": 6000
}

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

Update code and clients for 2025-11-01-preview

To complete your migration, follow these cleanup steps:

  1. For blob knowledge sources only, update clients to use the new index. If you have code or script that runs an indexer or references a data source, index, or skillset, make sure you update the references to the new objects.

  2. Replace all agent references with knowledgeBases in configuration files, code, scripts, and tests.

  3. Update client calls to use the 2025-11-01-preview.

  4. Clear or regenerate cached definitions that were created using the old shapes.

2025-08-01-preview

If you created a knowledge agent using the 2025-05-01-preview, your agent's definition includes an inline targetIndexes array and an optional defaultMaxDocsForReranker property.

Starting with the 2025-08-01-preview API version, reusable knowledge sources replace targetIndexes, and defaultMaxDocsForReranker is no longer supported. These breaking changes require you to:

  1. Get the current targetIndexes configuration
  2. Create an equivalent knowledge source
  3. Update the agent to use knowledgeSources instead of targetIndexes
  4. Send a query to test the retrieval
  5. Remove code that uses targetIndexes and update clients

Get the current configuration

To retrieve your agent's definition, use the 2025-05-01-preview of Knowledge Agents - Get (REST API).

@search-endpoint = <search-endpoint>
@agent-name = <agent-name>
@search-access-token = <search-access-token>

### Get agent definition
GET {{search-endpoint}}/agents/{{agent-name}}?api-version=2025-05-01-preview  HTTP/1.1
    Authorization: Bearer {{search-access-token}}

The response should be similar to the following example. Copy the indexName, defaultRerankerThreshold, and defaultIncludeReferenceSourceData values for use in the upcoming steps. defaultMaxDocsForReranker is deprecated, so you can ignore its value.

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "my-knowledge-agent",
  "description": "My description of the agent",
  "targetIndexes": [
    {
      "indexName": "my-index",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ]
}

Create a knowledge source

To create a searchIndex knowledge source, use the 2025-08-01-preview of Knowledge Sources - Create (REST API). Set searchIndexName to the value you previously copied.

@source-name = <source-name>

### Create a knowledge source
PUT {{search-endpoint}}/knowledgeSources/{{source-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
        "name": "{{source-name}}",
        "description": "My description of the knowledge source",
        "kind": "searchIndex",
        "searchIndexParameters": {
            "searchIndexName": "my-index"
        }
    }

The previous example creates a knowledge source that represents one index, but you can target multiple indexes or an Azure blob. For more information, see Create a knowledge source.

Update the agent

To replace targetIndexes with knowledgeSources in your agent's definition, use the 2025-08-01-preview of Knowledge Agents - Create or Update (REST API). Set rerankerThreshold and includeReferenceSourceData to the values you previously copied.

### Replace targetIndexes with knowledgeSources
POST {{search-endpoint}}/agents/{{agent-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
        "name": "{{agent-name}}",
        "knowledgeSources": [
            {
                "name": "{{source-name}}",
                "rerankerThreshold": 2.5,
                "includeReferenceSourceData": true
            }
        ]
    }

The previous example updates the definition to reference one knowledge source, but you can target multiple knowledge sources. You can also use other properties to control the retrieval behavior, such as alwaysQuerySource. For more information, see Create a knowledge agent.

Test the retrieval for 2025-08-01-preview updates

To test your agent's output with a query, use the 2025-08-01-preview of Knowledge Retrieval - Retrieve (REST API).

### Send a query to the agent
POST {{search-endpoint}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
      "messages": [
            {
                "role": "user",
                "content" : [
                    {
                        "text": "<query-text>",
                        "type": "text"
                    }
                ]
            }
        ]
    }

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

Update code and clients for 2025-08-01-preview

To complete your migration, follow these cleanup steps:

  • Replace all targetIndexes references with knowledgeSources in configuration files, code, scripts, and tests.
  • Update client calls to use the 2025-08-01-preview.
  • Clear or regenerate cached agent definitions that were created using the old shape.

Version-specific changes

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

2026-08-01-preview

The 2026-08-01-preview version builds on 2026-05-01-preview and includes breaking changes for applications that use Work IQ knowledge sources, offset-based list paging, model-backed activity records, MCP server result processing, or positional generated-client calls.

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

  • workIQParameters is required on a Work IQ knowledge source and must contain entraAppAuthentication. Update the source in place, or create a replacement for a side-by-side migration. Pass the user assertion in the x-ms-query-work-iq-source-authorization header on retrieve requests.

  • Work IQ references remove attributions, the WorkIQAttribution shape, and seeMoreWebUrl. The reshaped reference exposes searchSensitivityLabelInfo. Remove dependencies on the deleted fields, and update reference processing for the new sensitivity-label shape.

  • The preview-only $top, $skip, and $count parameters are removed. Collection list operations use search, pageSize, and searchType. Responses use @odata.nextLink for continuation paging. Update list requests, and follow each @odata.nextLink exactly as returned.

  • Query-planning, answer-synthesis, and web-summarization activity records remove the scalar modelName. The replacement model object contains modelName and deploymentId. Deserialize the nested model object for model-backed activity records.

  • McpServerTool.inclusionMode is removed. On each MCP server tools item, map reranked to resultsProcessing: "rerank" and always to resultsProcessing: "none". If omitted, resultsProcessing defaults to rerank; none bypasses reranking and preserves the underlying result order.

  • The new list parameters change generated method parameter order but don't affect REST parameter binding. Review positional calls after you install an SDK package that supports 2026-08-01-preview. Prefer named arguments or options where available.

2026-05-01-preview

2026-05-01-preview adds knowledge base, knowledge source, and retrieve features on top of 2025-11-01-preview without removing previously persisted properties. Existing knowledge bases and knowledge sources that you created in earlier preview versions continue to work. This version mostly exposes new functionality and reverts a few preview-only limits.

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

There are no breaking changes between 2025-11-01-preview and 2026-05-01-preview. Existing requests that target 2025-11-01-preview continue to work when you change the API version to 2026-05-01-preview.

The language SDKs that ship 2026-05-01-preview support introduce code-shape changes that are breaking at the SDK layer. See Update code and clients for 2026-05-01-preview for the full SDK shape mapping.

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 retrieve request 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 retrieve request 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 retrieve request:

    • rerankerThreshold
    • alwaysQuerySource
    • includeReferenceSourceData
    • includeReferences

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

  • Knowledge agent (base) retrieve request: 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 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