Migrieren den agentischen Abrufcode zur neuesten Version

Wenn Ihr agentischer Abrufcode auf eine frühere API-Version ausgerichtet ist, wird in diesem Artikel erläutert, wann und wie Sie zu einer neueren Version migrieren. Außerdem werden Änderungen, die Unterbrechungen verursachen, und Änderungen, die keine Unterbrechungen verursachen, für alle API-Versionen beschrieben, die den agentengestützten Abruf unterstützen.

Migrationsanweisungen sollen Ihnen helfen, eine vorhandene Lösung auf einer neueren API-Version auszuführen. Die Anweisungen in diesem Artikel helfen Ihnen bei der Behebung von Änderungen auf API-Ebene, damit Ihre App wie zuvor ausgeführt wird. Hilfe zum Hinzufügen neuer Funktionen finden Sie unter What's new in Azure KI-Suche.

Zeitpunkt der Migration

Die meisten Versionen, die den agentischen Abruf unterstützen, haben wesentliche Änderungen eingeführt. Sie können weiterhin älteren Code unverändert ausführen, indem Sie den WERT der API-Version beibehalten, aber um von Fehlerbehebungen, Verbesserungen und neueren Funktionen zu profitieren, müssen Sie Ihren Code aktualisieren.

Wenn Ihr Code auf eine Vorschauversion abzielt, empfehlen wir, nur dann auf die neueste stabile Version zu migrieren, wenn Ihr Anwendungsfall von 2026-04-01 vollständig unterstützt wird. Wenn Sie auf Antwortsynthese, nicht minimalen Denkaufwand oder mehrstufige Nachrichten angewiesen sind, überprüfen Sie die Breaking und Nonbreaking Änderungen, bevor Sie sich für eine Migration entscheiden. Diese Funktionen bleiben in der Vorschau.

Vor der Migration

• Um den Umfang der Änderungen zu verstehen, überprüfen Sie die grundlegenden und nicht grundlegenden Änderungen für jede Version.

• Der unterstützte Migrationspfad ist inkrementell. Wenn Ihr Code auf 2025-05-01-preview abzielt, migrieren Sie zunächst zu 2025-08-01-preview und fahren Sie dann mit jeder nachfolgenden Version fort, bis Sie die Zielversion erreicht haben.

• Erstellen Sie für eine parallele Migration eindeutig benannte Objekte, die das Verhalten der vorherigen Version implementieren. Bei diesem Ansatz bleiben vorhandene Objekte erhalten, während Sie Ersetzungen entwickeln und testen. Wenn ein Objekt eine direkte Aktualisierung unterstützt, weisen die versionsspezifischen Schritte auf diese Option hin.

• Für jedes objekt, das Sie migrieren, rufen Sie zunächst die aktuelle Definition aus dem Suchdienst ab, damit Sie vorhandene Eigenschaften überprüfen können, bevor Sie die neue angeben.

• Löschen Sie ältere Versionen erst, nachdem Ihre Migration vollständig getestet und bereitgestellt wurde.

Wie man migriert

In diesem Abschnitt werden die Migrationsschritte für die folgenden API-Versionen behandelt:

• 2026-08-01-Vorschau
• 2026-05-01-Vorschau
• 2026-04-01
• 2025-11-01-Vorschau
• 2025-08-01-Vorschau

2026-08-01-Vorschau

Wenn Sie von 2026-05-01-preview migrieren, können Sie direkt zu 2026-08-01-preview. Diese Migration erfordert Aktualisierungen von Work IQ-Wissensquellen, Listen paging, Antwortverarbeitung, MCP-Servertools und betroffenen generierten Clientanrufen.

1. Migrieren von Work IQ-Wissensquellen
2. Seitennummerierung von Listen aktualisieren
3. Verarbeitung von Abrufantworten aktualisieren
4. Aktualisieren von Code und Clients

Migrieren von Work IQ-Wissensquellen

So migrieren Sie eine Work IQ-Wissensquelle zur neuen Authentifizierungskonfiguration:

1. Exportieren Sie die aktuelle Definition.

2. Aktualisieren Sie die vorhandene Wissensquelle mithilfe von Wissensquellen – Erstellen oder Aktualisieren, oder erstellen Sie einen Ersatz mit einem eindeutigen Namen für eine parallele Migration.

3. Verwenden Sie die 2026-08-01-preview API-Version und konfigurieren Sie workIQParameters.entraAppAuthentication. Die Eigenschaften applicationId und federatedCredentialId sind erforderlich. Die tenantId Eigenschaft ist optional und standardmäßig auf den Mandanten des Suchdiensts festgelegt.

4. Wenn Sie einen Ersatz erstellt haben, aktualisieren Sie jede Wissensdatenbank, die auf die vorherige Wissensquelle verweist, um den Ersatznamen zu verwenden.

5. Aktualisieren Sie Abrufanforderungen so, dass die Benutzer-Assertion im Header x-ms-query-work-iq-source-authorization übergeben wird.

Informationen zu Setup und Beispielen finden Sie unter Create a Work IQ Knowledge Source (Vorschau).

Listenseitenaufteilung aktualisieren

So ersetzen Sie die Offset-basierte Paginierung durch die Cursor-basierte Paginierung:

1. Entfernen $top, , $skipund $count aus Wissensquellenlistenanforderungen. Legen Sie pageSize zwischen 1 und 3.000 fest, um die Seitengröße zu steuern. Wenn Sie es weglassen, wählt der Dienst das Seitenformat aus.

2. Um nach Namen zu filtern, legen Sie fest search und searchType. Der einzige unterstützte searchType Wert ist prefix, was auch der Standardwert ist. Die folgende Anfrage gibt maximal 100 Wissensquellen zurück, deren Namen mit contoso beginnen.

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

   Referenz:Wissensquellen - Liste

3. Wenn die Antwort enthält @odata.nextLink, senden Sie diese URL genau wie zurückgegeben. Parsen oder ändern Sie dessen Fortsetzungszustand nicht.

Abrufen der Antwortverarbeitung aktualisieren

So verarbeiten Sie die neue Work IQ-Referenz und modellgestützte Aktivitätsformen:

1. Entfernen von Abhängigkeiten von attributions, WorkIQAttribution, und seeMoreWebUrl. Lesen Sie Metadaten von Vertraulichkeitsbezeichnungen aus searchSensitivityLabelInfo in der Work IQ-Referenz.

2. Lesen Sie in Aktivitätsdatensätzen zur Abfrageplanung, Antwortsynthese und Webzusammenfassung deploymentId und model aus dem verschachtelten Objekt modelName. Das geschachtelte Objekt und beide Eigenschaften sind optional.

Die folgenden Fragmente zeigen die Änderungen an der Antwortstruktur.

{
  "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, verwenden dieselben Fragmente die folgende Form:

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

Code und Clients für 2026-08-01-preview aktualisieren

So schließen Sie Ihre Migration ab:

1. Ersetzen Sie inclusionMode auf jedem MCP-Serverelement tools durch resultsProcessing. Ordnen Sie rerankedrerank und alwaysnone zu. Der Wert rerank ist der standardmäßige Wert. Der none Wert umgeht die Neurankung und behält die zugrunde liegende Ergebnisreihenfolge des Tools bei. Informationen zum Einrichten finden Sie unter Konfigurieren von Tools für eine MCP-Server-Wissensquelle.

2. Wenn Sie eine Azure SDK verwenden, installieren Sie ein Paket, das Positionslistenaufrufe unterstützt2026-08-01-preview, und überprüfen Sie Positionslistenaufrufe für Parameterreihenfolgenänderungen. REST-Aufrufer sind nicht betroffen, da HTTP-Parameter nach Namen zugeordnet werden. Bevorzugen Sie in C# benannte Argumente, wie z. B. GetKnowledgeSourcesAsync(search: ..., pageSize: ...). Übergeben Sie in Python Listenoptionen als Schlüsselwortargumente.

3. Testen Sie die Work IQ-Authentifizierung und -referenzen, Cursor paging, Deserialisierung von Aktivitätsaufzeichnungen, MCP-Serverergebnisbestellungen und generierten Clientaufrufen, bevor Sie die Produktion aktualisieren.

4. Wenn Sie Ersatz-Work IQ-Wissensquellen erstellt haben, löschen Sie die früheren Quellen erst, nachdem die Migration alle Tests bestanden hat, ihre aktualisierte Anwendung bereitgestellt wird und keine Wissensbasis auf die früheren Namen verweist.

2026-05-01-Vorschau

Wenn Sie von 2026-04-01 oder 2025-11-01-preview migrieren, können Sie direkt zu 2026-05-01-preview. Anforderungen, Antworten und beibehaltene Objekte dieser Versionen bleiben kompatibel. Die Unterschiede sind additive Features und Sprach-SDK-Umbenennungen.

1. Aktualisieren Sie die API-Version in REST-Anforderungen auf 2026-05-01-preview. SDK-Clients verwenden die Standard-API-Version des Pakets, daher müssen Sie kein explizites serviceVersion Argument übergeben. Aktualisieren Sie stattdessen auf das 2026-05-01-preview SDK-Paket.

2. Wenn Sie das Python- oder JavaScript-SDK verwenden, aktualisieren Sie den abrufenden Client auf KnowledgeBaseRetrievalClient, und rufen Sie retrieve(...) anstelle der älteren retrieveKnowledge(...) auf. Die vollständige SDK-Shape-Zuordnung finden Sie unter Aktualisieren von Code und Clients für 2026-05-01-preview.

3. (Optional) Nutzen Sie die neuen 2026-05-01-preview Funktionen, z. B. aktualitätsbewusstes Abrufen, Dokumentobergrenzen pro Quelle und für Endergebnisse, gespeicherte Standardwerte für Abrufvorgänge, CORS für die Wissensdatenbank und Purview-Metadaten zu Vertraulichkeitsbezeichnungen in Abrufantworten. Keine dieser Features ist erforderlich, um eine vorhandene Lösung funktionsfähig zu halten.

Code und Clients für 2026-05-01-preview aktualisieren

Die 2026-05-01-preview SDKs führen Code-Shape-Änderungen in den unterstützten Sprachen ein:

Nachdem Sie die Client-Shapes aktualisiert haben, führen Sie den vollständigen Fluss aus, der den Index erstellt, Dokumente hochlädt, eine Wissensquelle erstellt, eine Wissensdatenbank erstellt, eine Abrufanforderung ausgibt und Ressourcen bereinigt, um das Ende der Migration zu bestätigen.

01.04.2026

Wenn Sie von 2025-11-01-preview migrieren, können Sie direkt auf 2026-04-01 migrieren. Der Index und der Inhalt bleiben unverändert. Sie müssen nur das Wissensbasisschema und das Abrufanforderungs-Shape aktualisieren.

1. Migrieren von Wissensquellen
2. Migrieren der Knowledge Base
3. Aktualisieren der Abrufanforderung
4. Aktualisieren der Abrechnungsgenehmigung
5. Aktualisieren von Code und Clients

Migrieren von Wissensquellen

In 2026-04-01 sind die Wissensquellentypen searchIndex, azureBlob, indexedOneLake und web allgemein verfügbar. Andere Wissensquellentypen bleiben in der Vorschau.

1. Verwenden Sie Wissensquellen – Get (REST API), um die aktuelle Definition abzurufen.

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

2. Identifizieren Sie in der Antwort, was weiterzuleiten ist und was entfernt werden soll:

   • Für searchIndex und web werden alle Eigenschaftswerte übernommen.

   • Für azureBlob und indexedOneLake übernehmen Sie alle Eigenschaftswerte, lassen jedoch ingestionPermissionOptions bei ingestionParameters weg. Diese Eigenschaft wird in 2026-04-01 nicht unterstützt.

3. Verwenden Sie Wissensquellen – Erstellen oder Aktualisieren (REST-API), um eine neue Wissensquelle mit einem eindeutigen Namen, der 2026-04-01 API-Version und den Eigenschaftswerten aus dem vorherigen Schritt zu erstellen.

   Das folgende Beispiel zeigt eine searchIndex Wissensquelle. Verwenden Sie ein ähnliches Muster für azureBlobindexedOneLake, und web Wissensquellen.

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

Migrieren der Knowledge Base

Die 2026-04-01 Knowledge Base hat ein einfacheres Schema als die Version 2025-11-01-preview: Sie behält knowledgeSources bei und verzichtet auf Einstellungen für die Antwortgenerierung. Überprüfen Sie die aktuelle Definition, bevor Sie ein neues Objekt erstellen.

1. Verwenden Sie Knowledge Basen – Abrufen (REST-API), um die aktuelle Definition abzurufen.

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

2. Identifizieren Sie in der Antwort, was weiterzuleiten ist und was entfernt werden soll:

   • Notieren Sie die Verweise knowledgeSources. Tragen Sie diese weiter in die neue Wissensbasis.

   • Wenn vorhanden, entfernen Sie outputMode, answerInstructions und retrievalInstructions. Diese Eigenschaften werden in 2026-04-01 nicht unterstützt.

   • Wenn Ihre Wissensbasis eine web Wissensquelle verwendet, behalten Sie bei models. Für den Webabruf ist eine modellgestützte Zusammenfassung erforderlich. Entfernen Sie modelsfür alle anderen Wissensquellentypen .

3. Verwenden Sie Knowledge Basen – Erstellen oder Aktualisieren (REST-API), um eine neue Wissensbasis mit einem eindeutigen Namen, der 2026-04-01 API-Version und nur den unterstützten Eigenschaften zu erstellen.

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

Aktualisieren der Abrufanforderung

Die 2026-04-01 Abrufanforderung weist ein anderes Shape als die Vorschauversion auf:

• Verwenden Sie intents anstelle von messages.

• Verwenden Sie maxOutputSizeInTokens anstelle von maxOutputSize.

• Wenn vorhanden, entfernen retrievalReasoningEffort und alwaysQuerySource. Diese Parameter werden in 2026-04-01 nicht unterstützt.

• Für Nachverfolgungsfragen senden Sie eine neue Abrufanforderung mit einer neuen semantischen Absicht. 2026-04-01 verwaltet keine laufende Nachrichtentranskription.

Verwenden Sie zum Testen der Knowledge Base-Ausgabe mit einer Abfrage die 2026-04-01 Version des Wissensabrufs – Abrufen (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
}

Wenn die Antwort über einen 200 OK HTTP-Code verfügt, hat Ihre Wissensdatenbank Inhalte erfolgreich aus der Wissensquelle abgerufen.

Aktualisieren der Abrechnungsgenehmigung

Ab der API-Version 2026-04-01 wird die Zustimmung zur Abrechnung für den agentischen Abruf durch eine dedizierte knowledgeRetrieval Eigenschaft gesteuert, die von semanticSearch getrennt ist, das nun nur noch für die Abrechnung des semantischen Rankers gilt. knowledgeRetrieval ist eine Eigenschaft der Verwaltungsebene, sodass Sie sie über die REST-API der Suchverwaltung und nicht über die REST-API des Suchdienstes festlegen.

Verwenden Sie die neueste Vorschauversion von Diensten – Erstellen oder Aktualisieren (REST-API), um für Ihren Suchdienst festzulegen knowledgeRetrieval .

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

Gültige Werte und Abrechnungsdetails finden Sie unter Agentenabrechnung aktivieren oder deaktivieren.

Aktualisieren Sie den Code und die Clients für den 01.04.2026.

So schließen Sie Ihre Migration ab:

1. Aktualisieren Sie Clientaufrufe, um die 2026-04-01 API-Version zu verwenden.

2. Aktualisieren Sie alle hartcodierten Knowledge Base- oder Knowledge Source-Namen in Ihrem Code, um auf die neuen Objekte zu verweisen, die während der Migration erstellt wurden.

3. Wenn Sie azureBlob oder indexedOneLake Wissensquellen migriert haben, aktualisieren Sie alle Codes oder Skripte, die namentlich auf den zugehörigen Index, den Indexer, die Datenquelle oder das Skillset verweisen, um auf die neuen Objekte zu zeigen.

4. Aktualisieren Sie den Code, der Abrufantworten verarbeitet. Die Antworten liefern extraktiven Bezugsinhalt mit activity und references, keine synthetisierten Antworten.

5. Löschen Sie Vorschauobjekte nur, nachdem die neuen Objekte vollständig überprüft und bereitgestellt wurden.

2025-11-01-Vorschau

Wenn Sie von 2025-08-01-Preview migrieren, wird "Wissens-Agent" in "Knowledge Base" umbenannt, und mehrere Eigenschaften werden in verschiedene Objekte und Ebenen innerhalb einer Objektdefinition verschoben.

1. Aktualisieren von SearchIndex-Wissensquellen
2. Aktualisieren von AzureBlob-Wissensquellen
3. Ersetzen von Wissensagenten durch Knowledge Base
4. Aktualisieren der Abrufanforderung und Senden einer Abfrage zum Testen Ihrer Updates
5. Aktualisieren von Clientcode

Aktualisieren einer SearchIndex-Wissensquelle

Dieses Verfahren erstellt eine neue 2025-11-01-previewsearchIndex Wissensquelle auf derselben Funktionalen Ebene wie die vorherige 2025-08-01 Version. Der zugrunde liegende Index selbst erfordert keine Aktualisierungen.

1. Auflisten aller Wissensquellen anhand des Namens, um Ihre Wissensquelle zu finden.

   ### 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. Rufen Sie die aktuelle Definition ab, um vorhandene Eigenschaften zu überprüfen.

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

   Die Antwort sollte dem folgenden Beispiel ähneln.

   {
        "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. Formulieren Sie eine Anforderung zum Erstellen von Wissensquellen als Grundlage für Ihre Migration.

   Beginnen Sie mit dem JSON der Version 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"
     }
   }
   

   Führen Sie die folgenden Updates für eine 2025-11-01-preview Migration aus:

   • Geben Sie der Wissensquelle einen neuen Namen.

   • Ändern Sie die API-Version in 2025-11-01-preview.

   • Benennen Sie sourceDataSelect in sourceDataFields um und ändern Sie die Zeichenfolge in ein Array mit Namen-Wert-Paaren für jedes abrufbare Feld, das Sie abfragen möchten. Dies sind die Felder, die in den Suchergebnissen zurückgegeben werden sollen, ähnlich einer select Klausel in einer klassischen Abfrage.

4. Überprüfen Sie Ihre Aktualisierungen, und senden Sie dann die Anforderung, um das Objekt zu erstellen.

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

Sie verfügen jetzt über eine migrierte searchIndex Wissensquelle, die mit der vorherigen Version rückwärtskompatibel ist und die korrekten Eigenschaftsspezifikationen für die 2025-11-01-preview verwendet.

Die Antwort enthält die vollständige Definition des neuen Objekts. Weitere Informationen zu neuen Eigenschaften, die diesem Wissensquelltyp zur Verfügung stehen, den Sie jetzt über Updates ausführen können, finden Sie unter How to create a search index knowledge source.

Aktualisieren einer AzureBlob-Wissensquelle

Dieses Verfahren erstellt eine neue 2025-11-01-previewazureBlob Wissensquelle auf derselben Funktionalen Ebene wie die vorherige 2025-08-01 Version. Es erstellt eine neue Gruppe von generierten Objekten: Datenquelle, Skillset, Indexer, Index.

1. Auflisten aller Wissensquellen anhand des Namens, um Ihre Wissensquelle zu finden.

   ### 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. Rufen Sie die aktuelle Definition ab, um vorhandene Eigenschaften zu überprüfen.

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

   Wenn Ihr Workflow ein Modell enthält, sollte die Antwort dem folgenden Beispiel ähneln. Beachten Sie, dass eine Antwort die Namen der generierten Objekte enthält. Diese Objekte sind vollständig unabhängig von der Wissensquelle und bleiben auch dann funktionsfähig, wenn Sie deren Wissensquelle aktualisieren oder löschen.

    {
      "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. Formulieren Sie eine Anforderung zum Erstellen von Wissensquellen als Grundlage für Ihre Migration.

   Beginnen Sie mit dem JSON der Version 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
     }
   }
   

   Führen Sie die folgenden Updates für eine 2025-11-01-preview Migration aus:

   • Geben Sie der Wissensquelle einen neuen Namen.

   • Ändern Sie die API-Version in 2025-11-01-preview.

   • Fügen Sie ingestionParameters als Container für die folgenden untergeordneten Eigenschaften hinzu: "embeddingModel", "chatCompletionModel", "ingestionSchedule", "contentExtractionMode".

4. Überprüfen Sie Ihre Aktualisierungen, und senden Sie dann die Anforderung, um das Objekt zu erstellen. Neue generierte Objekte werden für die Indexerpipeline erstellt.

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

Sie verfügen jetzt über eine migrierte azureBlob Wissensquelle, die mit der vorherigen Version rückwärtskompatibel ist und die korrekten Eigenschaftsspezifikationen für die 2025-11-01-preview verwendet.

Die Antwort enthält die vollständige Definition des neuen Objekts. Weitere Informationen zu neuen Eigenschaften, die für diesen Wissensquelltyp verfügbar sind, den Sie jetzt über Updates ausführen können, finden Sie unter Erstellen einer Blob-Wissensquelle.

Ersetzen von Wissensagenten durch Wissensbasis

1. Wissensbasen erfordern eine Wissensquelle. Stellen Sie sicher, dass Sie vor Beginn über eine Wissensquelle verfügen, die auf 2025-11-01-preview ausgerichtet ist.

2. Rufen Sie die aktuelle Definition ab, um vorhandene Eigenschaften zu überprüfen.

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

   Die Antwort sollte dem folgenden Beispiel ähneln.

   {
     "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. Formulieren Sie eine Create Knowledge Base-Anforderung als Grundlage für Ihre Migration.

   Beginnen Sie mit dem JSON der Version 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"
       }
   }
   

   Führen Sie die folgenden Updates für eine 2025-11-01-preview Migration aus:

   • Ersetzen Sie den Endpunkt: /knowledgebases/{{knowledge-base-name}}. Geben Sie der Wissensbasis einen eindeutigen Namen.

   • Ändern Sie die API-Version in 2025-11-01-preview.

   • Löschen requestLimits. Die Eigenschaften maxRuntimeInSeconds und maxOutputSize werden jetzt direkt in der Abrufanforderung angegeben.

   • Aktualisieren Sie knowledgeSources:

     • Löschen Sie maxSubQueries und ersetzen Sie es durch retrievalReasoningEffort (siehe Festlegen des Reasoning-Aufwands für die Retrieval-Funktion (Vorschau)).

   • Verschieben Sie alwaysQuerySource, includeReferenceSourceData, includeReferences und rerankerThreshold in den knowledgeSourceParams Bereich einer Abrufaktion.

   • Keine Änderungen für models.

   • Aktualisieren Sie outputConfiguration:

     • Ersetzen Sie outputConfiguration mit outputMode.

     • Löschen attemptFastPath. Es ist nicht mehr vorhanden. Das entsprechende Verhalten wird erzielt, indem retrievalReasoningEffort auf das Minimum gesetzt wird (siehe Festlegen des Reasoning-Aufwands für den Abruf (Vorschau)).

     • Wenn die Modalität auf answerSynthesis festgelegt ist, stellen Sie sicher, dass der Abrufbegründungsaufwand auf "Niedrig" (Standard) oder "Medium" festgelegt ist.

   • Fügen Sie ingestionParameters als Anforderung für die Erstellung einer 2025-11-01-preview azureBlob-Wissensquelle hinzu.

4. Überprüfen Sie Ihre Aktualisierungen, und senden Sie dann die Anforderung, um das Objekt zu erstellen. Neue generierte Objekte werden für die Indexerpipeline erstellt.

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

Sie verfügen jetzt über eine Wissensbasis anstelle eines Wissensagenten, und das Objekt ist abwärtskompatibel mit der vorherigen Version.

Die Antwort enthält die vollständige Definition des neuen Objekts. Weitere Informationen zu neuen Eigenschaften, die einer Knowledge Base zur Verfügung stehen, die Sie jetzt über Updates ausführen können, finden Sie unter How to create a knowledge base.

Aktualisierung und Test des Abrufs für die 2025-11-01-Vorschauupdates

Die Abrufanfrage wird für die 2025-11-01-preview so geändert, dass mehr Formen unterstützt werden, einschließlich einer einfacheren Anfrage, die die LLM-Verarbeitung minimiert. Weitere Informationen zum Abrufen in dieser Vorschau finden Sie unter Abrufen von Daten mithilfe einer Knowledge Base. In diesem Abschnitt wird erläutert, wie Sie Ihren Code aktualisieren.

1. Ändern Sie den /agents/retrieve Endpunkt in /knowledgebases/retrieve.

2. Ändern Sie die API-Version in 2025-11-01-preview.

3. An messages sind keine Änderungen erforderlich, wenn Sie low oder medium Aufwand für das Abrufen von Argumenten verwenden. Ersetzen Sie messages durch minimal, wenn Sie -Reasoning verwenden (siehe intents).

4. Ändern Sie knowledgeSourceParams, um alle Eigenschaften einzuschließen, die aus dem Agenten entfernt wurden: rerankerThreshold, alwaysQuerySource, includeReferenceSourceData, includeReferences.

5. Fügen Sie die Einstellung retrievalReasoningEffort zu minimum hinzu, wenn Sie attemptFastPath verwendet haben. Wenn Sie maxSubQueries verwendet haben, ist es nicht mehr vorhanden. Verwenden Sie die Einstellung retrievalReasoningEffort, um die Verarbeitung von Unterabfragen festzulegen (siehe Den Abruf-Inferenzaufwand festlegen (Vorschau)).

Um die Ausgabe Ihrer Wissensdatenbank anhand einer Abfrage zu testen, verwenden Sie den 2025-11-01-preview von 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
}

Wenn die Antwort über einen 200 OK HTTP-Code verfügt, hat Ihre Wissensdatenbank Inhalte erfolgreich aus der Wissensquelle abgerufen.

Aktualisieren von Code und Clients für 2025-11-01-Vorschau

Führen Sie die folgenden Bereinigungsschritte aus, um die Migration abzuschließen:

1. Aktualisieren Sie den Client nur bei Blob-Wissensquellen, damit er den neuen Index verwendet. Wenn Sie Über Code oder Skript verfügen, der einen Indexer ausführt oder auf eine Datenquelle, einen Index oder ein Skillset verweist, stellen Sie sicher, dass Sie die Verweise auf die neuen Objekte aktualisieren.

2. Ersetzen Sie alle Agentverweise durch knowledgeBases in Konfigurationsdateien, Code, Skripts und Tests.

3. Aktualisieren Sie Clientaufrufe zur Verwendung von 2025-11-01-preview.

4. Löschen oder generieren Sie zwischengespeicherte Definitionen, die mit den alten Shapes erstellt wurden.

2025-08-01-Vorschau

Wenn Sie einen Wissens-Agent mit 2025-05-01-preview erstellt haben, enthält die Definition Ihres Agents ein Inlinearray targetIndexes und eine optionale defaultMaxDocsForReranker-Eigenschaft.

Ab der API-Version 2025-08-01-preview ersetzen wiederverwendbare Wissensquellen targetIndexes, und defaultMaxDocsForReranker wird nicht mehr unterstützt. Für diese bahnbrechenden Änderungen müssen Sie folgende Schritte ausführen:

1. Abrufen der aktuellen targetIndexes Konfiguration
2. Erstellen einer gleichwertigen Wissensquelle
3. Aktualisieren Sie den Agent, um knowledgeSources anstelle von targetIndexes zu verwenden
4. Senden einer Abfrage zum Testen des Abrufs
5. Entfernen Sie Code, der targetIndexes verwendet, und aktualisieren Sie die Clients

Abrufen der aktuellen Konfiguration

Um die Definition Ihres Agenten abzurufen, verwenden Sie die 2025-05-01-preview von 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}}

Die Antwort sollte dem folgenden Beispiel ähneln. Kopieren Sie die Werte von indexName, defaultRerankerThreshold und defaultIncludeReferenceSourceData zur Verwendung in den kommenden Schritten. defaultMaxDocsForReranker ist veraltet, sodass Sie den Wert ignorieren können.

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

Erstellen einer Wissensquelle

Verwenden Sie zum Erstellen einer searchIndex Wissensquelle die 2025-08-01-previewWissensquellen – Erstellen (REST-API). Setzen Sie searchIndexName auf den Wert, den Sie zuvor kopiert haben.

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

Im vorherigen Beispiel wird eine Wissensquelle erstellt, die einen Index darstellt, Sie können jedoch mehrere Indizes oder ein Azure BLOB als Ziel festlegen. Weitere Informationen finden Sie unter Erstellen einer Wissensquelle.

Aktualisieren des Agents

Um durch targetIndexes in der Definition Ihres Agents zu ersetzen, verwenden Sie das knowledgeSources von 2025-08-01-preview. Legen Sie rerankerThreshold und includeReferenceSourceData auf die Werte fest, die Sie zuvor kopiert haben.

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

Im vorherigen Beispiel wird die Definition aktualisiert, um auf eine Wissensquelle zu verweisen, Sie können jedoch mehrere Wissensquellen ansprechen. Sie können auch andere Eigenschaften verwenden, um das Abrufverhalten zu steuern, zum Beispiel alwaysQuerySource. Weitere Informationen finden Sie unter Erstellen eines Wissensagenten.

Testen des Abrufs für 2025-08-01-Vorschau-Updates

Um die Ausgabe Ihres Agenten mit einer Abfrage zu testen, verwenden Sie den 2025-08-01-preview von 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"
                    }
                ]
            }
        ]
    }

Wenn die Antwort über einen 200 OK HTTP-Code verfügt, hat Ihr Agent Inhalte erfolgreich aus der Wissensquelle abgerufen.

Aktualisieren Sie Code und Clients für 2025-08-01-Preview

Führen Sie die folgenden Bereinigungsschritte aus, um die Migration abzuschließen:

• Ersetzen Sie alle targetIndexes Verweise durch knowledgeSources in Konfigurationsdateien, Code, Skripts und Tests.
• Aktualisieren Sie Clientaufrufe zur Verwendung von 2025-08-01-preview.
• Löschen oder regenerieren Sie im Cache gespeicherte Agentendefinitionen, die mit der alten Form erstellt wurden.

Versionsspezifische Änderungen

In diesem Abschnitt werden Breaking und Nonbreaking Changes für die folgenden API-Versionen behandelt:

• 2026-08-01-Vorschau
• 2026-05-01-Vorschau
• 2026-04-01
• 2025-11-01-Vorschau
• 2025-08-01-Vorschau
• 2025-05-01-Vorschau

2026-08-01-Vorschau

Die 2026-08-01-preview-Version baut auf 2026-05-01-preview auf und enthält Breaking Changes für Anwendungen, die Work IQ-Wissensquellen, offsetbasierte Paginierung von Listen, modellgestützte Aktivitätsdatensätze, die Verarbeitung von MCP-Serverergebnissen oder positionsbasierte Aufrufe generierter Clients verwenden.

Um die REST-API-Referenzdokumentation für diese Version zu überprüfen, wählen Sie oben auf der Seite den 2026-08-01-preview API-Versionsfilter aus.

2026-05-01-Vorschau

2026-05-01-preview fügt Knowledge Base-, Knowledge Source- und Retrieve-Funktionen auf Basis von 2025-11-01-preview hinzu, ohne bereits gespeicherte Eigenschaften zu entfernen. Vorhandene Wissensdatenbanken und Wissensquellen, die Sie in früheren Vorschauversionen erstellt haben, funktionieren weiterhin. Diese Version führt hauptsächlich neue Funktionen ein und nimmt einige Beschränkungen zurück, die nur für die Vorschau galten.

Um die REST-API-Referenzdokumentation für diese Version zu überprüfen, wählen Sie oben auf der Seite den 2026-05-01-preview API-Versionsfilter aus.

01.04.2026

2026-04-01 ist die erste stabile API-Version für den agentischen Abruf. Es richtet einen minimalen, extraktiven Abrufvertrag ein und entfernt nachrichtenbasierte Abfrageplanungs- und Antwortsynthesefunktionen der Vorschauversion.

Um die REST-API-Referenzdokumentation für diese Version zu überprüfen, wählen Sie oben auf der Seite den 2026-04-01 API-Versionsfilter aus.

2025-11-01-Vorschau

Um die REST-API-Referenzdokumentation für diese Version zu überprüfen, wählen Sie oben auf der Seite den 2025-11-01-preview API-Versionsfilter aus.

2025-08-01-Vorschau

Um die REST-API-Referenzdokumentation für diese Version zu überprüfen, wählen Sie oben auf der Seite den 2025-08-01-preview API-Versionsfilter aus.

2025-05-01-Vorschau

Diese API-Version führt agentische Abruf- und Wissens-Agents ein. Jede Agentdefinition erfordert ein targetIndexes-Array, das einen einzelnen Index und optionale Eigenschaften angibt, wie z. B. defaultRerankerThreshold und defaultIncludeReferenceSourceData.

Um die REST-API-Referenzdokumentation für diese Version zu überprüfen, wählen Sie oben auf der Seite den 2025-05-01-preview API-Versionsfilter aus.

Verwandte Inhalte

• Agentic-Abruf in Azure KI-Suche
• Erstellen einer Wissensbasis
• Abfragen einer Wissensbasis