Migrate agentic retrieval code to the latest version

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 retrieval 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
   api-key: {{api-key}}
   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
   api-key: {{api-key}}
   Content-Type: application/json
   

   The response should look 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 {{url}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
   api-key: {{key}}
   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 {{url}}/knowledge-sources/search-index-ks-11-01?api-version=2025-11-01-preview
   api-key: {{key}}
   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 is backwards 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
   api-key: {{api-key}}
   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
   api-key: {{api-key}}
   Content-Type: application/json
   

   The response might look similar to the following example if your workflow includes a model. 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 {{url}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
   api-key: {{key}}
   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 {{url}}/knowledge-sources/azure-blob-ks-11-01?api-version=2025-11-01-preview
   api-key: {{key}}
   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 is backwards 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 an Azure Blob knowledge source.

Replace knowledge agent with knowledge base

1. Knowledge bases require a knowledge source. Make sure 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
   api-key: {{api-key}}
   Content-Type: application/json
   

   The response might look 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 {{url}}/knowledgebases/earth-at-night?api-version=2025-08-01-preview  HTTP/1.1
   api-key: {{key}}
   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/{{your-object-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 retrieval request object directly

   • Update knowledgeSources:

     • Delete maxSubQueries and replace with a retrievalReasoningEffort` (see Set the retrieval reasoning effort).

     • Move alwaysQuerySource, includeReferenceSourceData, includeReferences, and rerankerThreshold to the knowledgeSourcesParams 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).

     • 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 {{url}}/knowledgebases/earth-at-night-11-01?api-version={{api-version}}
    api-key: {{key}}
    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 backwards 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 retrieval 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 are using a low or medium retrievalReasoningEffort. Replace messages with intent if you use minimal reasoning (see Set the retrieval reasoning effort).

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

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 {{url}}/knowledgebases/earth-at-night-11-01/retrieve?api-version=2025-11-01-preview
api-key: {{key}}
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 Azure 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.

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, 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-url = <YourSearchServiceUrl>
@agent-name = <YourAgentName>
@api-key = <YourApiKey>

### Get agent definition
GET https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview  HTTP/1.1
    api-key: {{api-key}}

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", // Copy this value
      "defaultRerankerThreshold": 2.5, // Copy this value
      "defaultIncludeReferenceSourceData": true, // Copy this value
      "defaultMaxDocsForReranker": 100
    }
  ],
  ... // Redacted for brevity
}

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 = <YourSourceName>

### Create a knowledge source
PUT https://{{search-url}}/knowledgeSources/{{source-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    api-key: {{api-key}}

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

This 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 https://{{search-url}}/agents/{{agent-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    api-key: {{api-key}}

    { 
        "name": "{{agent-name}}", 
        "knowledgeSources": [  
            {  
                "name": "{{source-name}}",
                "rerankerThreshold": 2.5, // Use the previous value
                "includeReferenceSourceData": true // Use the previous value
            }
        ]
    } 

This 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 https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    api-key: {{api-key}}

    {
      "messages": [
            {
                "role": "user",
                "content" : [
                    {
                        "text": "<YourQueryText>",
                        "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.

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

• Adds knowledge sources for OneLake, SharePoint (local), SharePoint (remote) that retrieves content directly from Sharepoint, Web (Bing) that pulls from the Bing indexes.

• All knowledge sources that pull from a search index have new ingestion options: ingestionPermissionOptions to support source-specific access models, contentExtractionMode that enables Azure Content Understanding in Foundry Tools integration, aiServices endpoint for Azure Content Understanding when "contentExtractionMode": "minimal".

• All knowledge sources that pull from a search index have a status operation, which returns the synchronization status of the knowledge source with its data source.

• The searchIndex knowledge source adds semanticConfigurationName that overrides the default semantic configuration used by the retrieval request.

• The searchIndex knowledge source adds sourceDataFields and searchDataFields to specify which fields are used at query time and also returned in a response.

• Knowledge agent (base) retrieval responses now return HTTP 206 status codes for partial success. Retrieval requests now take an optional retrievalReasoningEffort property that specifies levels of LLM processing (see Set the retrieval reasoning effort).

• Knowledge agent (base) adds a new intent object for minimal retrieval reasoning effort, where intent replaces messages to the LLM. An intent is a query string passed directly to the search engine, with no intermediate LLM query planning step.

• Activity records in the retrieval response now have an optional error output, which indicates if the activity represents a failed operation.

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

• Adds knowledgeSources, outputConfiguration, and retrievalInstructions to agent definitions. For information about supported properties, see Create a knowledge agent.

• Renames defaultRerankerThreshold to rerankerThreshold and defaultIncludeReferenceSourceData to includeReferenceSourceData. These properties previously existed in targetIndexes, but you now specify them within each knowledge source reference in knowledgeSources.