Migrate agentic retrieval code to the latest version

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

When to migrate

Migrate your agentic retrieval code when any of the following apply:

• The REST API version you use is announced for retirement or enters a deprecation window.

• A newer REST API version introduces breaking changes that affect features you use. For example, you must address breaking changes if your code targets the 2025-05-01-preview, which uses targetIndexes in agent definitions.

• You want features that are only available in a newer REST API version.

• Your code fails when unrecognized properties are returned in a REST API response. As a best practice, your application should ignore properties it doesn't understand.

How to migrate

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

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

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 REST API versions:

• 2025-08-01-preview
• 2025-05-01-preview

2025-08-01-preview

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.

Related content

• Create a knowledge agent
• Create a knowledge source