Migrer le code de récupération agentique vers la dernière version

Si votre code de récupération agentique cible une version antérieure de l’API, cet article explique quand et comment migrer vers une version plus récente. Il décrit également les modifications importantes et moins importantes pour toutes les versions de l’API qui prennent en charge la récupération agentique.

Les instructions de migration sont destinées à vous aider à exécuter une solution existante sur une version plus récente de l’API. Les instructions fournies dans cet article vous aident à résoudre les modifications disruptives au niveau de l’API afin que votre application fonctionne comme avant. Pour obtenir de l'aide sur l'ajout de nouvelles fonctionnalités, commencez par Nouveautés de Recherche Azure AI.

Quand migrer

La plupart des versions qui prennent en charge la récupération agentique ont introduit des modifications cassantes. Vous pouvez continuer à exécuter du code plus ancien inchangé en conservant la valeur de version de l’API, mais pour tirer parti des correctifs de bogues, des améliorations et des fonctionnalités plus récentes, vous devez mettre à jour votre code.

Si votre code cible une préversion, nous vous recommandons de migrer vers la dernière version stable uniquement si votre cas d’utilisation est entièrement pris en charge par 2026-04-01. Si vous vous appuyez sur la synthèse des réponses, l’effort de raisonnement non minimal ou les messages à plusieurs tour, passez en revue les modifications cassantes et sans rupture avant de décider de migrer. Ces fonctionnalités restent en préversion.

Avant de procéder à la migration

• Pour comprendre l’étendue des modifications, passez en revue les changements majeurs et mineurs pour chaque version.

• Le chemin de migration pris en charge est incrémentiel. Si votre code cible 2025-05-01-preview, commencez par migrer vers 2025-08-01-preview, puis passez à chaque version ultérieure jusqu’à atteindre votre version cible.

• Pour une migration côte à côte, créez des objets nommés de manière unique qui implémentent les comportements de la version précédente. Cette approche conserve les objets existants pendant que vous développez et testez les remplacements. Si un objet prend en charge la mise à jour sur place, les étapes spécifiques à la version mentionnent cette possibilité.

• Pour chaque objet que vous migrez, commencez par obtenir la définition actuelle à partir du service de recherche afin de pouvoir passer en revue les propriétés existantes avant de spécifier la nouvelle.

• Supprimez les versions antérieures uniquement une fois votre migration entièrement testée et déployée.

Comment migrer

Cette section décrit les étapes de migration pour les versions d’API suivantes :

• 2026-08-01-preview
• Aperçu du 01-05-2026
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview

2026-08-01-preview

Si vous migrez à partir de 2026-05-01-preview, vous pouvez passer directement à 2026-08-01-preview. Cette migration nécessite la mise à jour des sources de connaissances Work IQ, de la pagination des listes, du traitement des réponses, des outils du serveur MCP et des appels du client généré concernés.

1. Migrer les sources de connaissances de Work IQ
2. Mettre à jour la pagination de liste
3. Mettre à jour le traitement des réponses de récupération
4. Mettre à jour le code et les clients

Migrer les sources de connaissances de Work IQ

Pour migrer une source de connaissances Work IQ vers la nouvelle configuration d’authentification :

1. Exportez sa définition actuelle.

2. Mettez à jour la source de connaissances existante à l’aide de sources de connaissances - Créer ou mettre à jour, ou créez un remplacement par un nom unique pour une migration côte à côte.

3. Utilisez la version de l’API 2026-08-01-preview et configurez workIQParameters.entraAppAuthentication. Les applicationId propriétés et federatedCredentialId sont obligatoires. La tenantId propriété est facultative et correspond par défaut au locataire du service de recherche.

4. Si vous avez créé un remplacement, mettez à jour chaque base de connaissances qui référence la source de connaissances précédente pour utiliser le nom de remplacement.

5. Mettez à jour les requêtes de récupération pour transmettre l’assertion de l’utilisateur dans l’en-tête x-ms-query-work-iq-source-authorization.

Pour la configuration et des exemples, consultez Créer une source de connaissances Work IQ (préversion).

Mettre à jour la pagination de liste

Pour remplacer la pagination basée sur le décalage par la pagination basée sur le curseur :

1. Supprimez $skip, $count et $top des demandes de liste de sources de connaissances. Définissez pageSize de 1 à 3 000 pour contrôler la taille de la page. Si vous l’omettez, le service choisit la taille de la page.

2. Pour filtrer par nom, définissez search et searchType. La seule valeur prise en charge searchType est prefix, qui est également la valeur par défaut. La requête suivante retourne jusqu’à 100 sources de connaissances dont les noms commencent par contoso.

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

   Référence :Sources de connaissances - Liste

3. Si la réponse contient @odata.nextLink, envoyez cette URL exactement comme retournée. N’analysez ni ne modifiez son état de continuation.

Mettre à jour le traitement des réponses de récupération

Pour traiter la nouvelle référence Work IQ et les formes d’activité adossées au modèle :

1. Supprimez les dépendances sur attributions, WorkIQAttributionet seeMoreWebUrl. Lire les métadonnées de l’étiquette de confidentialité dans la référence Work IQ à partir de searchSensitivityLabelInfo.

2. Dans les enregistrements d’activité de planification des requêtes, de synthèse des réponses et de résumé web, lisez modelName et deploymentId à partir de l’objet imbriqué model. L’objet imbriqué et les deux propriétés sont facultatifs.

Les fragments suivants montrent les modifications apportées à la forme de réponse.

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

Dans 2026-08-01-preview, les mêmes fragments utilisent la forme suivante :

{
  "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>"
      }
    }
  ]
}

Mettre à jour le code et les clients pour 2026-08-01-preview

Pour terminer votre migration :

1. Sur chaque élément de serveur tools MCP, remplacez inclusionMode par resultsProcessing. Mappez reranked à always et rerank à none. La valeur par défaut est rerank. La none valeur contourne la reclassement et conserve l’ordre de résultat sous-jacent de l’outil. Pour la configuration, consultez Configurer des outils pour une source de connaissances du serveur MCP.

2. Si vous utilisez un Kit de développement logiciel (SDK) Azure, installez un package qui prend en charge 2026-08-01-previewet examinez les appels de liste positionnelle pour les modifications de l’ordre des paramètres. Les appelants REST ne sont pas affectés, car les paramètres HTTP sont clés par nom. En C#, préférez les arguments nommés, tels que GetKnowledgeSourcesAsync(search: ..., pageSize: ...). Dans Python, passez des options de liste en tant qu’arguments de mot clé.

3. Testez l’authentification Work IQ et les références, la pagination par curseur, la désérialisation des enregistrements d’activité, l’ordre des résultats du serveur MCP et les appels du client généré avant de mettre à jour l’environnement de production.

4. Si vous avez créé des sources de connaissances Work IQ de remplacement, supprimez les sources antérieures uniquement une fois que la migration a réussi tous les tests, votre application mise à jour est déployée et aucune base de connaissances ne fait référence aux noms précédents.

Aperçu du 01-05-2026

Si vous migrez à partir de 2026-04-01 ou 2025-11-01-preview, vous pouvez passer directement à 2026-05-01-preview. Les requêtes, réponses et objets persistants de ces versions restent compatibles. Les différences sont les fonctionnalités additives et les renommages du SDK de langage.

1. Mettez à jour la version de l’API vers 2026-05-01-preview dans les requêtes REST. Les clients du KIT de développement logiciel (SDK) utilisent la version d’API par défaut du package. Vous n’avez donc pas besoin de passer un argument explicite serviceVersion . Au lieu de cela, effectuez une mise à niveau vers le package sdk 2026-05-01-preview .

2. Si vous utilisez le SDK Python ou JavaScript, mettez à jour le client retrieve vers KnowledgeBaseRetrievalClient et appelez retrieve(...) au lieu de l’ancienne version retrieveKnowledge(...). Pour obtenir le mappage complet des formes du SDK, consultez Mettre à jour le code et les clients pour 2026-05-01-preview.

3. (Facultatif) Adoptez les nouvelles fonctionnalités 2026-05-01-preview, telles que la récupération tenant compte de la fraîcheur, les plafonds de documents par source et pour le résultat final, les paramètres de récupération par défaut persistants, la prise en charge de CORS pour la base de connaissances et les métadonnées des étiquettes de confidentialité Purview dans les réponses de récupération. Aucune de ces fonctionnalités n’est nécessaire pour conserver une solution existante.

Mettre à jour le code et les clients pour 2026-05-01-preview

Les 2026-05-01-preview kits SDK introduisent des modifications de forme de code dans les langages pris en charge :

Après avoir mis à jour les formes clientes, exécutez le flux complet qui crée l’index, charge des documents, crée une source de connaissances, crée une base de connaissances, émet une demande de récupération et nettoie les ressources pour confirmer la migration de bout en bout.

01/04/2026

Si vous migrez de 2025-11-01-preview, vous pouvez migrer directement vers 2026-04-01. Votre index et votre contenu restent inchangés. Vous devez uniquement mettre à jour le schéma de la base de connaissances et la forme de demande de récupération.

1. Migrer les sources de connaissances
2. Migrer la base de connaissances
3. Mettre à jour la demande de récupération
4. Mettre à jour le consentement de facturation
5. Mettre à jour le code et les clients

Migrer des sources de connaissances

Dans 2026-04-01, les types de sources de connaissances searchIndex, indexedOneLake, azureBlob et web sont généralement disponibles. D’autres types de bases de connaissances restent en préversion.

1. Utilisez les sources de connaissances - Obtenir (API REST) pour obtenir la définition actuelle.

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

2. Dans la réponse, identifiez les éléments à transférer et les éléments à supprimer :

   • Pour searchIndex et web, transférez toutes les valeurs de propriété.

   • Pour azureBlob et indexedOneLake, transférer toutes les valeurs de propriété, mais omettre ingestionPermissionOptions de ingestionParameters. Cette propriété n’est pas prise en charge dans 2026-04-01.

3. Utilisez les sources de connaissances - Créer ou mettre à jour (API REST) pour créer une nouvelle source de connaissances avec un nom unique, la version de l’API 2026-04-01 et les valeurs de propriété de l’étape précédente.

   L’exemple suivant montre une searchIndex source de connaissances. Utilisez un modèle similaire pour les sources de connaissances azureBlob, indexedOneLake, et web.

   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" }
       ]
     }
   }
   

Migrer la base de connaissances

La 2026-04-01 base de connaissances a un schéma plus simple que la version : elle conserve knowledgeSources et supprime les paramètres de 2025-11-01-preview génération de réponses. Passez en revue la définition actuelle avant de créer un objet.

1. Utilisez les bases de connaissances - Obtenir (API REST) pour obtenir la définition actuelle.

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

2. Dans la réponse, identifiez les éléments à transférer et les éléments à supprimer :

   • Notez les références knowledgeSources. Transférez celles-ci dans la nouvelle base de connaissances.

   • S’il est présent, supprimez outputMode, answerInstructionset retrievalInstructions. Ces propriétés ne sont pas prises en charge dans 2026-04-01.

   • Si votre base de connaissances utilise une web source de connaissances, conservez models. La récupération web nécessite une synthèse basée sur un modèle. Pour tous les autres types de sources de connaissances, supprimez models.

3. Utilisez les bases de connaissances - Créer ou mettre à jour (API REST) pour créer une base de connaissances avec un nom unique, la version de l’API 2026-04-01 et uniquement les propriétés prises en charge.

   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}}" }
     ]
   }
   

Mettre à jour la demande de récupération

La 2026-04-01 demande de récupération a une forme différente de la version préliminaire :

• Utilisez intents plutôt messagesque .

• Utilisez maxOutputSizeInTokens plutôt maxOutputSizeque .

• S’il est présent, supprimez retrievalReasoningEffort et alwaysQuerySource. Ces paramètres ne sont pas pris en charge dans 2026-04-01.

• Pour les questions de suivi, envoyez une nouvelle demande de récupération avec une nouvelle intention sémantique. 2026-04-01 ne conserve pas une transcription de messages en cours d’exécution.

Pour tester la sortie de votre base de connaissances avec une requête, utilisez la 2026-04-01 version de la récupération des connaissances - Récupérer (API REST).

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
}

Si la réponse a un 200 OK code HTTP, votre base de connaissances a correctement récupéré du contenu à partir de la source de connaissances.

Mettre à jour le consentement de facturation

À partir de la version 2026-04-01 de l’API, le consentement à la facturation de la récupération agentique est géré par une propriété knowledgeRetrieval dédiée, distincte de semanticSearch, qui ne s’applique désormais qu’à la facturation du classeur sémantique. knowledgeRetrieval est une propriété de plan de gestion. Vous l’avez donc définie par le biais de l’API REST gestion de la recherche, et non de l’API REST du service de recherche.

Utilisez la dernière préversion des services - Créer ou mettre à jour (API REST) pour définir knowledgeRetrieval sur votre service de recherche.

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"
  }
}

Pour connaître les valeurs valides et les détails de facturation, consultez Activer ou désactiver la facturation de récupération agentique.

Mettre à jour le code et les clients pour 2026-04-01

Pour terminer votre migration :

1. Mettez à jour les appels clients pour utiliser la version de l’API 2026-04-01 .

2. Mettez à jour les noms de base de connaissances ou de source de connaissances codés en dur dans votre code pour référencer les nouveaux objets créés lors de la migration.

3. Si vous avez migré azureBlob ou indexedOneLake des sources de connaissances, mettez à jour tout code ou script qui référence l’index, l’indexeur, la source de données ou l’ensemble de compétences associé par nom afin de les lier aux nouveaux éléments migrés.

4. Mettez à jour le code qui traite la récupération des réponses. Les réponses renvoient du contenu de base extrait avec activity et references, et non des réponses synthétisées.

5. Supprimez les objets en préversion uniquement une fois que les nouveaux objets sont entièrement validés et déployés.

2025-11-01-aperçu

Si vous migrez de 2025-08-01-preview, l'« agent de connaissances » est renommé en « base de connaissances », et plusieurs propriétés sont déplacées vers différents objets et niveaux au sein d’une définition d’objet.

1. Mettre à jour les sources de connaissances searchIndex
2. Mettre à jour les sources de connaissances azureBlob
3. Remplacer l’agent de connaissances par la base de connaissances
4. Mettre à jour la demande de récupération et envoyer une requête pour tester vos mises à jour
5. Mettre à jour le code client

Mettre à jour une source de connaissances searchIndex

Cette procédure crée une nouvelle 2025-11-01-previewsearchIndex source de connaissances au même niveau fonctionnel que la version précédente 2025-08-01 . L’index sous-jacent lui-même ne nécessite aucune mise à jour.

1. Répertoriez toutes les sources de connaissances par nom pour rechercher votre source de connaissances.

   ### 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. Obtenez la définition actuelle pour passer en revue les propriétés existantes.

   ### 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
   

   La réponse doit être similaire à l’exemple suivant.

   {
        "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. Formulez une requête Créer une source de connaissances comme base pour votre migration.

   Commencez par le json 08-01-preview.

   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"
     }
   }
   

   Effectuez les mises à jour suivantes pour une 2025-11-01-preview migration :

   • Donnez à la source de connaissances un nouveau nom.

   • Remplacez la version de l’API par 2025-11-01-preview.

   • Renommez sourceDataSelect en sourceDataFields et modifiez la chaîne pour en faire un tableau avec des paires nom-valeur pour chaque champ récupérable que vous souhaitez consulter. Il s’agit des champs à retourner dans les résultats de recherche, comme une select clause dans une requête classique.

4. Passez en revue vos mises à jour, puis envoyez la demande pour créer l’objet.

   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" }
           ]
       }
   }
   

Vous disposez maintenant d’une source de connaissances migrée searchIndex rétrocompatible avec la version précédente, utilisant les spécifications de propriété appropriées pour le 2025-11-01-preview.

La réponse inclut la définition complète du nouvel objet. Pour plus d’informations sur les nouvelles propriétés disponibles pour ce type de source de connaissances, que vous pouvez désormais effectuer via des mises à jour, consultez Comment créer une source de connaissances d’index de recherche.

Mettre à jour une source de connaissances AzureBlob

Cette procédure crée une nouvelle 2025-11-01-previewazureBlob source de connaissances au même niveau fonctionnel que la version précédente 2025-08-01 . Il crée un nouvel ensemble d’objets générés : source de données, ensemble de compétences, indexeur, index.

1. Répertoriez toutes les sources de connaissances par nom pour rechercher votre source de connaissances.

   ### 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. Obtenez la définition actuelle pour passer en revue les propriétés existantes.

   ### 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
   

   Si votre flux de travail inclut un modèle, la réponse doit être similaire à l’exemple suivant. Notez qu’une réponse inclut les noms des objets générés. Ces objets sont entièrement indépendants de la source de connaissances et restent opérationnels même si vous mettez à jour ou supprimez leur source de connaissances.

    {
      "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. Formulez une requête Créer une source de connaissances comme base pour votre migration.

   Commencez par le json 08-01-preview.

   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
     }
   }
   

   Effectuez les mises à jour suivantes pour une 2025-11-01-preview migration :

   • Donnez à la source de connaissances un nouveau nom.

   • Remplacez la version de l’API par 2025-11-01-preview.

   • Ajoutez ingestionParameters en tant que conteneur pour les propriétés enfants suivantes : "embeddingModel", "chatCompletionModel", "ingestionSchedule", "contentExtractionMode".

4. Passez en revue vos mises à jour, puis envoyez la demande pour créer l’objet. Les nouveaux objets générés sont créés pour le pipeline de l’indexeur.

   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"
           }
       }
   }
   

Vous disposez maintenant d’une source de connaissances migrée azureBlob rétrocompatible avec la version précédente, utilisant les spécifications de propriété appropriées pour le 2025-11-01-preview.

La réponse inclut la définition complète du nouvel objet. Pour plus d’informations sur les nouvelles propriétés disponibles pour ce type de source de connaissances, que vous pouvez désormais effectuer via des mises à jour, consultez Créer une source de connaissances d’objet blob.

Remplacer l’agent de connaissances par la base de connaissances

1. Les bases de connaissances nécessitent une source de connaissances. Vérifiez que vous disposez d’une source de connaissances qui cible 2025-11-01-preview avant de commencer.

2. Obtenez la définition actuelle pour passer en revue les propriétés existantes.

   ### 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
   

   La réponse doit être similaire à l’exemple suivant.

   {
     "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. Formulez une demande de création Créer une base de connaissances pour votre migration.

   Commencez par le json 08-01-preview.

   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"
       }
   }
   

   Effectuez les mises à jour suivantes pour une 2025-11-01-preview migration :

   • Remplacez le point de terminaison : /knowledgebases/{{knowledge-base-name}}. Donnez à la base de connaissances un nom unique.

   • Remplacez la version de l’API par 2025-11-01-preview.

   • Supprimer requestLimits. Les propriétés maxRuntimeInSeconds et maxOutputSize sont désormais spécifiées directement dans la requête de récupération.

   • Mise à jour knowledgeSources:

     • Supprimez maxSubQueries et remplacez-le par retrievalReasoningEffort (voir Définir l’effort de raisonnement pour la récupération (version préliminaire)).

   • Déplacez alwaysQuerySource, includeReferenceSourceData, includeReferences, et rerankerThreshold vers la section knowledgeSourceParams d’une action de récupération.

   • Aucune modification pour models.

   • Mise à jour outputConfiguration:

     • Remplacez outputConfiguration par outputMode.

     • Supprimer attemptFastPath. Il n’existe plus. Un comportement équivalent est obtenu en définissant retrievalReasoningEffort sur la valeur minimale (voir Définir l’effort de raisonnement pour la récupération (version préliminaire)).

     • Si la modalité est définie sur answerSynthesis, veillez à définir l’effort de raisonnement pour la récupération sur faible (valeur par défaut) ou moyen.

   • Ajoutez ingestionParameters comme condition préalable pour créer une source de connaissances Azure Blob 2025-11-01-preview.

4. Passez en revue vos mises à jour, puis envoyez la demande pour créer l’objet. Les nouveaux objets générés sont créés pour le pipeline de l’indexeur.

    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."
    }
   

Vous disposez maintenant d’une base de connaissances au lieu d’un agent de connaissances, et l’objet est rétrocompatible avec la version précédente.

La réponse inclut la définition complète du nouvel objet. Pour plus d’informations sur les nouvelles propriétés disponibles pour une base de connaissances, que vous pouvez désormais effectuer via des mises à jour, consultez Comment créer une base de connaissances.

Mise à jour et test de la récupération pour les mises à jour 2025-11-01-preview

La requête de récupération est modifiée pour prendre en charge davantage de formats pour le 2025-11-01-preview, y compris une requête plus simple qui minimise le traitement par le LLM. Pour plus d’informations sur la récupération dans cette préversion, consultez Récupérer des données à l’aide d’une base de connaissances. Cette section explique comment mettre à jour votre code.

1. Remplacez le point de terminaison /agents/retrievepar /knowledgebases/retrieve .

2. Remplacez la version de l’API par 2025-11-01-preview.

3. Aucune modification de messages n’est nécessaire si vous utilisez low ou medium un effort de raisonnement de récupération. Remplacez messages par intents si vous utilisez le raisonnement minimal (voir Définir le niveau d’effort du raisonnement de récupération (version préliminaire)).

4. Modifiez knowledgeSourceParams pour inclure toutes les propriétés qui ont été supprimées de l’agent : rerankerThreshold, alwaysQuerySource, includeReferenceSourceData, . includeReferences

5. Ajoutez retrievalReasoningEffort défini à minimum si vous utilisiez attemptFastPath. Si vous utilisiez maxSubQueries, il n’existe plus. Utilisez le paramètre retrievalReasoningEffort pour spécifier le traitement des sous-requêtes (voir Définir l’effort de raisonnement pour la récupération (version préliminaire)).

Pour tester la réponse de votre base de connaissances à l’aide d’une requête, utilisez le 2025-11-01-preview de Extraction de connaissances - Récupérer (API REST).

### 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
}

Si la réponse a un 200 OK code HTTP, votre base de connaissances a correctement récupéré du contenu à partir de la source de connaissances.

Mettre à jour le code et les clients pour 2025-11-01-preview

Pour effectuer votre migration, suivez ces étapes de nettoyage :

1. Pour les sources de connaissances blob uniquement, mettez à jour les clients pour utiliser le nouvel index. Si vous avez du code ou un script qui exécute un indexeur ou référence une source de données, un index ou un ensemble de compétences, veillez à mettre à jour les références aux nouveaux objets.

2. Remplacez toutes les références d'agent par knowledgeBases dans les fichiers de configuration, le code, les scripts et les tests.

3. Mettez à jour les appels client pour utiliser 2025-11-01-preview.

4. Effacez ou régénérez les définitions mises en cache créées à l’aide des anciennes formes.

2025-08-01-preview

Si vous avez créé un agent de connaissance à l’aide de la préversion 2025-05-01, la définition de votre agent inclut un tableau en ligne et une propriété facultative targetIndexes.

À compter de la version de l’API 2025-08-01-preview , les sources de connaissances réutilisables remplacent targetIndexeset defaultMaxDocsForReranker ne sont plus prises en charge. Ces modifications disruptives nécessitent que vous :

1. Obtenir la configuration actuelle targetIndexes
2. Créer une source de connaissances équivalente
3. Mettre à jour l’agent à utiliser knowledgeSources au lieu de targetIndexes
4. Envoyer une requête pour tester la récupération
5. Supprimer le code qui utilise targetIndexes et met à jour les clients

Obtenir la configuration actuelle

Pour récupérer la définition de votre assistant, utilisez 2025-05-01-preview de Assistants de connaissance - Obtenir (API REST).

@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}}

La réponse doit être similaire à l’exemple suivant. Copiez les valeurs indexName, defaultRerankerThreshold, et defaultIncludeReferenceSourceData pour utilisation dans les étapes à venir. defaultMaxDocsForReranker est déconseillé, de sorte que vous pouvez ignorer sa valeur.

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

Créer une source de connaissances

Pour créer une searchIndex source de connaissances, utilisez les 2025-08-01-previewsources de connaissances - Créer (API REST). Attribuez à searchIndexName la valeur que vous avez copiée précédemment.

@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"
        }
    }

L’exemple précédent crée une source de connaissances qui représente un index, mais vous pouvez cibler plusieurs index ou un objet blob Azure. Pour plus d’informations, consultez Créer une source de connaissances.

Mettre à jour l’agent

Pour remplacer targetIndexes par knowledgeSources dans la définition de votre agent, utilisez le 2025-08-01-preview de Agents de connaissances - Créer ou mettre à jour (API REST). Définissez rerankerThreshold et includeReferenceSourceData aux valeurs que vous avez copiées précédemment.

### 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
            }
        ]
    }

L’exemple précédent met à jour la définition pour référencer une source de connaissances, mais vous pouvez cibler plusieurs sources de connaissances. Vous pouvez également utiliser d'autres propriétés pour contrôler le comportement de récupération, telles que alwaysQuerySource, par exemple. Pour plus d’informations, consultez Créer un agent de connaissances.

Tester la récupération des mises à jour 2025-08-01-preview

Pour tester la sortie de votre assistant avec une requête, utilisez le 2025-08-01-preview de Extraction de connaissances - Récupérer (API REST).

### 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"
                    }
                ]
            }
        ]
    }

Si la réponse a un 200 OK code HTTP, votre agent a correctement récupéré du contenu à partir de la source de connaissances.

Mettre à jour le code et les clients pour la pré-version du 1er août 2025.

Pour effectuer votre migration, suivez ces étapes de nettoyage :

• Remplacez toutes les références targetIndexes par knowledgeSources dans les fichiers de configuration, le code, les scripts et les tests.
• Mettez à jour les appels client pour utiliser 2025-08-01-preview.
• Effacez ou régénérez les définitions d’agent mises en cache qui ont été créées à l’aide de l’ancienne forme.

Modifications spécifiques à la version

Cette section couvre les modifications avec rupture de compatibilité et sans rupture de compatibilité pour les versions d’API suivantes :

• 2026-08-01-preview
• Aperçu du 01-05-2026
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview
• 2025-05-01-preview

2026-08-01-preview

La 2026-08-01-preview version s’appuie sur la préversion 2026-05-01 et inclut des changements cassants pour les applications qui utilisent des sources de connaissances Work IQ, la pagination basée sur un décalage, les enregistrements d’activité basés sur des modèles, le traitement des résultats du serveur MCP ou les appels générés par un client de position.

Pour consulter la documentation de référence de l’API REST pour cette version, sélectionnez le 2026-08-01-preview filtre de version de l’API en haut de la page.

Aperçu du 01-05-2026

2026-05-01-preview ajoute la base de connaissances, la source de connaissances et récupère les fonctionnalités en plus de 2025-11-01-preview sans supprimer les propriétés précédemment persistantes. Les bases de connaissances existantes et les sources de connaissances que vous avez créées dans les versions préliminaires antérieures continuent de fonctionner. Cette version expose principalement de nouvelles fonctionnalités et rétablit quelques limites en préversion uniquement.

Pour consulter la documentation de référence de l’API REST pour cette version, sélectionnez le 2026-05-01-preview filtre de version de l’API en haut de la page.

01/04/2026

2026-04-01 est la première version stable de l’API pour la récupération agentique. Il établit un contrat minimal de récupération extractif et supprime les fonctionnalités de planification des requêtes basées sur les messages et de synthèse des réponses en préversion.

Pour consulter la documentation de référence de l’API REST pour cette version, sélectionnez le 2026-04-01 filtre de version de l’API en haut de la page.

2025-11-01-aperçu

Pour consulter la documentation de référence de l’API REST pour cette version, sélectionnez le 2025-11-01-preview filtre de version de l’API en haut de la page.

2025-08-01-preview

Pour consulter la documentation de référence de l’API REST pour cette version, sélectionnez le 2025-08-01-preview filtre de version de l’API en haut de la page.

2025-05-01-preview

Cette version de l’API introduit les agents de récupération et de connaissances agentiques. Chaque définition d’agent nécessite un targetIndexes tableau qui spécifie un index unique et des propriétés facultatives, telles que defaultRerankerThreshold et defaultIncludeReferenceSourceData.

Pour consulter la documentation de référence de l’API REST pour cette version, sélectionnez le 2025-05-01-preview filtre de version de l’API en haut de la page.

Contenu connexe

• Recherche agentique dans Recherche Azure AI
• Créer une base de connaissances
• Interroger une base de connaissances