エージェント検索コードを最新バージョンに移行する

エージェント検索コードが以前の API バージョンを対象とする場合、この記事では、新しいバージョンに移行するタイミングと方法について説明します。 また、エージェント検索をサポートするすべての API バージョンの破壊的変更と非破壊的変更についても説明します。

移行手順は、新しい API バージョンで既存のソリューションを実行するのに役立ちます。 この記事の手順は、API レベルで重大な変更に対処し、アプリが以前と同様に実行されるようにするのに役立ちます。 新しい機能の追加については、 Azure AI 検索。

移行するタイミング

エージェント検索をサポートするほとんどのバージョンでは、破壊的変更が導入されました。 API バージョンの値を保持することで、古いコードを引き続き変更せずに実行できますが、バグ修正、機能強化、および新しい機能の恩恵を受けるには、コードを更新する必要があります。

コードがプレビュー バージョンを対象とする場合は、ユース ケースが 2026-04-01 で完全にサポートされている場合にのみ、最新の安定バージョンに移行することをお勧めします。 回答の合成、非最小限の推論作業、または複数ターンのメッセージに依存する場合は、移行を決定する前に破壊的変更と非破壊的変更を確認してください。 これらの機能はプレビューのままです。

移行前に

• 変更の範囲を理解するには、各バージョン の破壊的変更と非破壊的変更を 確認します。

• サポートされている移行パスは段階的です。 コードが 2025-05-01-previewをターゲットとする場合は、最初に 2025-08-01-previewに移行してから、ターゲット バージョンに到達するまで後続の各バージョンを続行します。

• サイド バイ サイド移行の場合は、前のバージョンの動作を実装する一意の名前付きオブジェクトを作成します。 この方法では、置換の開発とテスト中に既存のオブジェクトが保持されます。 オブジェクトがインプレース更新をサポートしている場合、バージョン固有の手順でそのオプションが呼び出されます。

• 移行するオブジェクトごとに、まず検索サービスから現在の定義を取得し、新しいプロパティを指定する前に既存のプロパティを確認できるようにします。

• 移行が完全にテストされ、デプロイされた後にのみ、古いバージョンを削除します。

移行方法

このセクションでは、次の API バージョンの移行手順について説明します。

• 2026-08-01-preview
• 2026-05-01-プレビュー
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview

2026-08-01-preview

2026-05-01-preview から移行する場合は、2026-08-01-previewに直接移動できます。 この移行には、Work IQ ナレッジ ソース、リスト ページング、応答処理、MCP サーバー ツール、影響を受ける生成されたクライアント呼び出しの更新が必要です。

1. Work IQ ナレッジ ソースを移行する
2. リストのページングを更新する
3. 応答の取得処理を更新する
4. コードとクライアントを更新する

Work IQ ナレッジ ソースを移行する

Work IQ ナレッジ ソースを新しい認証構成に移行するには:

1. 現在の定義をエクスポートします。

2. ナレッジ ソース - 作成または更新を使用して既存のナレッジ ソースを更新するか、サイド バイ サイド移行の一意の名前で置換を作成します。

3. 2026-08-01-preview API バージョンを使用し、workIQParameters.entraAppAuthenticationを構成します。 applicationId プロパティと federatedCredentialId プロパティは必須です。 tenantId プロパティは省略可能であり、既定では検索サービスのテナントに設定されます。

4. 置換を作成した場合は、前のナレッジ ソースを参照する各ナレッジ ベースを更新して、置換名を使用します。

5. 取得リクエストを更新して、x-ms-query-work-iq-source-authorization ヘッダー内でユーザー アサーションを渡します。

セットアップと例については、「 Work IQ ナレッジ ソースの作成 (プレビュー)」を参照してください。

リストのページングを更新する

オフセットベースのページングをカーソルベースのページングに置き換えるには:

1. ナレッジ ソース リスト要求から $top、 $skip、および $count を削除します。 ページ サイズを制御するには、 pageSize を 1 から 3,000 に設定します。 省略すると、サービスによってページ サイズが選択されます。

2. 名前でフィルター処理するには、 search と searchTypeを設定します。 サポートされている searchType 値は prefix のみです。これも既定値です。 次の要求は、名前が contoso で始まる最大 100 のナレッジ ソースを返します。

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

   リファレンス:ナレッジ ソース - リスト

3. 応答に @odata.nextLinkが含まれている場合は、返されたとおりにその URL を送信します。 継続状態を解析または変更しないでください。

応答の取得処理を更新する

新しい Work IQ リファレンスとモデル対応のアクティビティ シェイプを処理するには:

1. attributions、WorkIQAttribution、およびseeMoreWebUrlへの依存関係を削除します。 Work IQ リファレンス上の searchSensitivityLabelInfo から秘密度ラベルのメタデータを読み取ります。

2. クエリ計画、回答合成、および Web 要約アクティビティ レコードでは、入れ子になったmodel オブジェクトからmodelNameとdeploymentIdを読み取ります。 入れ子になったオブジェクトと両方のプロパティは省略可能です。

次のフラグメントは、応答図形の変化を示しています。

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

2026-08-01-previewでは、同じフラグメントで次の図形が使用されます。

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

2026-08-01-preview のコードとクライアントを更新する

移行を完了するには:

1. 各 MCP サーバー tools 項目で、 inclusionMode を resultsProcessingに置き換えます。 rerankedをrerankにマップし、noneをalwaysにマップします。 rerank 値が既定値です。 none値は、再ランク付けをバイパスし、ツールの基になる結果の順序を保持します。 セットアップについては、 MCP サーバーのナレッジ ソースのツールの構成を参照してください。

2. Azure SDKを使用する場合は、2026-08-01-previewをサポートするパッケージをインストールし、位置指定リストの呼び出しでパラメーター順序の変更を確認します。 HTTP パラメーターは名前でキー指定されるため、REST 呼び出し元は影響を受けません。 C# では、 GetKnowledgeSourcesAsync(search: ..., pageSize: ...)などの名前付き引数を使用します。 Pythonで、キーワード引数としてリスト オプションを渡します。

3. 運用環境を更新する前に、Work IQ の認証と参照、カーソル ページング、アクティビティ レコードの逆シリアル化、MCP サーバーの結果の順序付け、生成されたクライアント呼び出しをテストします。

4. 代替の Work IQ ナレッジ ソースを作成した場合は、移行がすべてのテストに合格し、更新されたアプリケーションがデプロイされ、以前の名前を参照するナレッジ ベースがない場合にのみ、以前のソースを削除します。

2026-05-01-プレビュー

2026-04-01 または 2025-11-01-preview から移行する場合は、2026-05-01-previewに直接移動できます。 これらのバージョンからの要求、応答、および永続化されたオブジェクトには互換性が維持されます。 違いは、追加機能と言語 SDK の名前変更です。

1. REST 要求で API バージョンを 2026-05-01-preview するように更新します。 SDK クライアントはパッケージの既定の API バージョンを使用するため、明示的な serviceVersion 引数を渡す必要はありません。 代わりに、 2026-05-01-preview SDK パッケージにアップグレードします。

2. Pythonまたは JavaScript SDK を使用する場合は、取得クライアントを KnowledgeBaseRetrievalClient に更新し、レガシ retrieve(...) の代わりに retrieveKnowledge(...) を呼び出します。 完全な SDK シェイプ マッピングについては、 2026-05-01-preview のコードとクライアントの更新に関する記事を参照してください。

3. (任意) 2026-05-01-preview の新機能 (たとえば、鮮度を考慮した取得、ソースごとおよび最終結果のドキュメント上限、永続化された取得の既定値、ナレッジ ベースの CORS、取得応答内の Purview の秘密度ラベル メタデータなど) を採用します。 既存のソリューションを動作させ続けるために、これらの機能は必要ありません。

2026-05-01-preview のコードとクライアントを更新する

2026-05-01-preview SDK では、サポートされている言語全体でコードシェイプの変更が導入されています。

クライアント図形を更新した後、インデックスの作成、ドキュメントのアップロード、ナレッジ ソースの作成、ナレッジ ベースの作成、取得要求の発行、リソースのクリーンアップを行って、移行をエンドツーエンドで確認するフル フローを実行します。

2026年4月1日

2025-11-01-preview から移行する場合は、2026-04-01に直接移行できます。 インデックスとコンテンツは変更されません。 必要なのは、ナレッジ ベース スキーマと取得要求の図形のみです。

1. ナレッジ ソースを移行する
2. ナレッジ ベースを移行する
3. 取得要求を更新する
4. 課金の同意を更新する
5. コードとクライアントを更新する

ナレッジ ソースを移行する

2026-04-01では、searchIndex、azureBlob、indexedOneLake、webナレッジ ソースの種類が一般公開されています。 その他のナレッジ ソースの種類はプレビューのままです。

1. ナレッジ ソース - Get (REST API) を使用して現在の定義を取得します。

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

2. 応答で、繰り越す内容と削除する内容を特定します。

   • searchIndexとwebの場合は、すべてのプロパティ値を繰り越します。

   • azureBlobとindexedOneLakeの場合は、すべてのプロパティ値を繰り越しますが、ingestionPermissionOptionsからingestionParametersは省略します。 このプロパティは、 2026-04-01ではサポートされていません。

3. ナレッジ ソース - 作成または更新 (REST API) を使用して、一意の名前、2026-04-01 API のバージョン、および前の手順のプロパティ値を持つ新しいナレッジ ソースを作成します。

   次の例は、 searchIndex ナレッジ ソースを示しています。 azureBlob、indexedOneLake、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" }
       ]
     }
   }
   

ナレッジ ベースを移行する

2026-04-01ナレッジ ベースには、2025-11-01-preview バージョンよりも単純なスキーマがあります。knowledgeSourcesが保持され、応答生成設定が削除されます。 新しいオブジェクトを作成する前に、現在の定義を確認します。

1. ナレッジ ベース - Get (REST API) を使用して現在の定義を取得します。

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

2. 応答で、繰り越す内容と削除する内容を特定します。

   • knowledgeSources参照に注意してください。 これらを新しいナレッジ ベースに転送します。

   • 存在する場合は、 outputMode、 answerInstructions、および retrievalInstructionsを削除します。 これらのプロパティは、 2026-04-01ではサポートされていません。

   • ナレッジ ベースで web ナレッジ ソースが使用されている場合は、 modelsを維持します。 Web の取得には、モデルに基づく要約が必要です。 その他のすべてのナレッジ ソースの種類については、 modelsを削除します。

3. ナレッジ ベース - 作成または更新 (REST API) を使用して、一意の名前、2026-04-01 API バージョン、サポートされているプロパティのみを含む新しいナレッジ ベースを作成します。

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

取得要求を更新する

2026-04-01取得要求の形状は、プレビュー バージョンとは異なります。

• intentsの代わりにmessagesを使用します。

• maxOutputSizeInTokensの代わりにmaxOutputSizeを使用します。

• 存在する場合は、 retrievalReasoningEffort と alwaysQuerySourceを削除します。 これらのパラメーターは、 2026-04-01ではサポートされていません。

• フォローアップの質問については、新しいセマンティック意図を使用して新しい取得要求を送信します。 2026-04-01 では、実行中のメッセージ トランスクリプトは保持されません。

クエリを使用してナレッジ ベースの出力をテストするには、ナレッジ取得 - 取得 (REST API) の2026-04-01バージョンを使用します。

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
}

応答に 200 OK HTTP コードがある場合、ナレッジ ベースはナレッジ ソースからコンテンツを正常に取得しました。

課金の同意を更新する

2026-04-01 API バージョンから、agentic retrieval の課金への同意は、knowledgeRetrieval とは別の専用の semanticSearch プロパティによって制御されるようになりました。knowledgeRetrieval は現在、セマンティック ランカーの課金にのみ適用されます。 knowledgeRetrieval は管理プレーン プロパティであるため、Search Service REST API ではなく Search Management REST API を使用して設定します。

最新のプレビュー バージョンの サービス - 作成または更新 (REST API) を使用して、検索サービスに 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"
  }
}

有効な値と課金の詳細については、「 エージェント検索の課金を有効または無効にする」を参照してください。

2026-04-01 のコードとクライアントを更新する

移行を完了するには:

1. 2026-04-01 API バージョンを使用するようにクライアント呼び出しを更新します。

2. コード内のハードコーディングされたナレッジ ベースまたはナレッジ ソース名を更新して、移行中に作成された新しいオブジェクトを参照します。

3. azureBlobまたはindexedOneLakeナレッジ ソースを移行した場合は、関連付けられているインデックス、インデクサー、データ ソース、またはスキルセットを参照するコードまたはスクリプトを、新しいオブジェクトを指す名前で更新します。

4. 応答の取得を処理するコードを更新します。 応答は、合成された回答ではなく、 activity と referencesを含む抽出接地コンテンツを返します。

5. 新しいオブジェクトが完全に検証され、配置された後にのみ、プレビュー オブジェクトを削除します。

2025-11-01-preview

2025-08-01-preview から移行する場合、"ナレッジ エージェント" の名前が "ナレッジ ベース" に変更され、オブジェクト定義内の異なるオブジェクトとレベルに複数のプロパティが再配置されます。

1. searchIndex ナレッジ ソースを更新する
2. azureBlob ナレッジ ソースを更新する
3. ナレッジ エージェントをナレッジ ベースに置き換える
4. 取得要求を更新し、更新をテストするクエリを送信する
5. クライアント コードを更新する

searchIndex ナレッジ ソースを更新する

この手順では、以前の2025-08-01 バージョンと同じ機能レベルで新しい2025-11-01-previewsearchIndexナレッジ ソースを作成します。 基になるインデックス自体に更新は必要ありません。

1. すべてのナレッジ ソースを名前で一覧表示して、ナレッジ ソースを検索します。

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

2. 既存のプロパティを 確認する現在の定義を取得します。

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

   応答は、次の例のようになります。

   {
        "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. 移行の基礎として 、ナレッジ ソースの作成 要求を作成します。

   08-01-preview JSON から始めます。

   POST {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
       "name": "search-index-ks",
       "kind": "searchIndex",
       "description": "A sample search index knowledge source",
       "encryptionKey": null,
       "searchIndexParameters": {
           "searchIndexName": "my-search-index",
           "sourceDataSelect": "id, page_chunk, page_number"
     }
   }
   

   2025-11-01-preview移行用に次の更新を行います。

   • ナレッジ ソースに新しい名前を付けます。

   • API のバージョンを 2025-11-01-preview に変更します。

   • sourceDataSelectの名前をsourceDataFieldsに変更し、クエリを実行する各取得可能なフィールドの名前と値のペアを持つ配列に文字列を変更します。 これらは、クラシック クエリの select 句と同様に、検索結果で返すフィールドです。

4. 更新プログラムを確認し、オブジェクトを作成する要求を送信します。

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

これで、searchIndexに対する正しいプロパティ仕様を使用した、以前のバージョンとの下位互換性がある移行済みの2025-11-01-previewナレッジソースを利用できるようになりました。

応答には、新しいオブジェクトの完全な定義が含まれます。 このナレッジ ソースの種類で使用できる新しいプロパティの詳細については、「 検索インデックスのナレッジ ソースを作成する方法」を参照してください。

azureBlob ナレッジ ソースを更新する

この手順では、以前の2025-08-01 バージョンと同じ機能レベルで新しい2025-11-01-previewazureBlobナレッジ ソースを作成します。 生成されたオブジェクトの新しいセット (データ ソース、スキルセット、インデクサー、インデックス) が作成されます。

1. すべてのナレッジ ソースを名前で一覧表示して、ナレッジ ソースを検索します。

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

2. 既存のプロパティを 確認する現在の定義を取得します。

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

   ワークフローにモデルが含まれている場合、応答は次の例のようになります。 応答には、生成されたオブジェクトの名前が含まれていることに注意してください。 これらのオブジェクトはナレッジ ソースから完全に独立しており、ナレッジ ソースを更新または削除しても動作し続けます。

    {
      "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. 移行の基礎として 、ナレッジ ソースの作成 要求を作成します。

   08-01-preview JSON から始めます。

   POST {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
       "name": "azure-blob-ks",
       "kind": "azureBlob",
       "description": "A sample azure blob knowledge source.",
       "encryptionKey": null,
       "azureBlobParameters": {
           "connectionString": "<redacted>",
           "containerName": "blobcontainer",
           "folderPath": null,
           "disableImageVerbalization": false,
           "identity": null,
           "embeddingModel": {
               "name": "embedding-model",
               "kind": "azureOpenAI",
               "azureOpenAIParameters": {
               "resourceUri": "<redacted>",
               "deploymentId": "text-embedding-3-large",
               "apiKey": "<redacted>",
               "modelName": "text-embedding-3-large",
               "authIdentity": null
               },
               "customWebApiParameters": null,
               "aiServicesVisionParameters": null,
               "amlParameters": null
           },
           "chatCompletionModel": null,
           "ingestionSchedule": null
     }
   }
   

   2025-11-01-preview移行用に次の更新を行います。

   • ナレッジ ソースに新しい名前を付けます。

   • API のバージョンを 2025-11-01-preview に変更します。

   • ingestionParametersを、"embeddingModel"、"chatCompletionModel"、"ingestionSchedule"、"contentExtractionMode"の子プロパティのコンテナーとして追加します。

4. 更新プログラムを確認し、オブジェクトを作成する要求を送信します。 インデクサー パイプライン用に新しく生成されたオブジェクトが作成されます。

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

これで、azureBlobに対する正しいプロパティ仕様を使用した、以前のバージョンとの下位互換性がある移行済みの2025-11-01-previewナレッジソースを利用できるようになりました。

応答には、新しいオブジェクトの完全な定義が含まれます。 このナレッジ ソースの種類で使用できる新しいプロパティの詳細については、「 BLOB ナレッジ ソースの作成」を参照してください。

ナレッジ エージェントをナレッジ ベースに置き換える

1. ナレッジ ベースにはナレッジ ソースが必要です。 開始する前に、 2025-11-01-preview を対象とするナレッジ ソースがあることを確認します。

2. 既存のプロパティを 確認する現在の定義を取得します。

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

   応答は、次の例のようになります。

   {
     "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. 移行の基礎として ナレッジ ベースの作成 要求を作成します。

   08-01-preview JSON から始めます。

   PUT {{search-endpoint}}/knowledgebases/earth-at-night?api-version=2025-08-01-preview  HTTP/1.1
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
       "name": "earth-at-night",
       "description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.",
       "retrievalInstructions": null,
       "encryptionKey": null,
       "knowledgeSources": [
           {
             "name": "earth-at-night",
             "alwaysQuerySource": null,
             "includeReferences": null,
             "includeReferenceSourceData": null,
             "maxSubQueries": null,
             "rerankerThreshold": 2.5
           }
       ],
       "models": [
           {
               "kind": "azureOpenAI",
               "azureOpenAIParameters": {
                   "resourceUri": "<redacted>",
                   "apiKey": "<redacted>",
                   "deploymentId": "gpt-5-mini",
                   "modelName": "gpt-5-mini"
               }
           }
       ],
       "outputConfiguration": {
           "modality": "answerSynthesis"
       }
   }
   

   2025-11-01-preview移行用に次の更新を行います。

   • エンドポイントを置き換えます: /knowledgebases/{{knowledge-base-name}}。 ナレッジ ベースに一意の名前を付けます。

   • API のバージョンを 2025-11-01-preview に変更します。

   • requestLimitsを削除します。 取得要求で maxRuntimeInSeconds プロパティと maxOutputSize プロパティが直接指定されるようになりました。

   • knowledgeSourcesの更新:

     • maxSubQueriesを削除し、retrievalReasoningEffortに置き換えます (取得の理由の設定 (プレビュー) を参照)。

   • alwaysQuerySource、includeReferenceSourceData、includeReferences、rerankerThresholdをknowledgeSourceParamsの セクションに移動します。

   • modelsの変更はありません。

   • outputConfigurationの更新:

     • outputConfigurationをoutputModeに置き換えます。

     • attemptFastPathを削除します。 存在しなくなりました。 同等の動作は、retrievalReasoningEffort を最小値に設定することで実現されます（取得推論の労力を設定する (プレビュー) を参照）。

     • モダリティを answerSynthesis に設定している場合は、取得プロセスの負荷を低 (既定) または中に設定していることを確認します。

   • 2025-11-01-preview azureBlob ナレッジ ソースを作成するための要件として、ingestionParametersを追加します。

4. 更新プログラムを確認し、オブジェクトを作成する要求を送信します。 インデクサー パイプライン用に新しく生成されたオブジェクトが作成されます。

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

ナレッジ エージェントではなくナレッジ ベースが作成され、オブジェクトは以前のバージョンと下位互換性があります。

応答には、新しいオブジェクトの完全な定義が含まれます。 ナレッジ ベースで使用できる新しいプロパティの詳細については、「ナレッジ ベースを作成する方法」を参照してください。

2025-11-01-preview 更新プログラムの取得を更新してテストする

取得要求は、LLM 処理を最小限に抑える単純な要求など、より多くの図形をサポートするために、 2025-11-01-preview に対して変更されます。 このプレビューでの取得の詳細については、「 ナレッジ ベースを使用したデータの取得」を参照してください。 このセクションでは、コードを更新する方法について説明します。

1. /agents/retrieve エンドポイントを /knowledgebases/retrieve に変更します。

2. API のバージョンを 2025-11-01-preview に変更します。

3. lowまたはmediumの取得の理由付け作業を使用している場合、messagesを変更する必要はありません。 minimal推論を使用する場合は、messagesをintentsに置き換えます (取得の理由の設定 (プレビュー) を参照)。

4. エージェントから削除されたすべてのプロパティ (knowledgeSourceParams、rerankerThreshold、alwaysQuerySource、includeReferenceSourceData) を含むようにincludeReferencesを変更します。

5. retrievalReasoningEffortを使用していた場合は、minimumにattemptFastPathを追加します。 maxSubQueriesを使用していた場合は、存在しなくなります。 retrievalReasoningEffort設定を使用して、サブクエリ処理を指定します (取得理由の設定 (プレビュー) を参照してください)。

クエリを使用してナレッジ ベースの出力をテストするには、ナレッジ取得 - 取得 (REST API) の2025-11-01-previewを使用します。

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

応答に 200 OK HTTP コードがある場合、ナレッジ ベースはナレッジ ソースからコンテンツを正常に取得しました。

2025-11-01-preview のコードとクライアントを更新する

移行を完了するには、次のクリーンアップ手順に従います。

1. BLOB ナレッジ ソースの場合のみ、新しいインデックスを使用するようにクライアントを更新します。 インデクサーを実行するコードまたはスクリプトがある場合、またはデータ ソース、インデックス、またはスキルセットを参照している場合は、必ず新しいオブジェクトへの参照を更新してください。

2. すべてのエージェント参照を、構成ファイル、コード、スクリプト、およびテストの knowledgeBases に置き換えます。

3. 2025-11-01-previewを使用するようにクライアント呼び出しを更新します。

4. 古い図形を使用して作成されたキャッシュされた定義をクリアまたは再生成します。

2025-08-01-preview

2025-05-01-preview を使用してナレッジ エージェントを作成した場合、エージェントの定義にはインラインtargetIndexes配列とオプションのdefaultMaxDocsForReranker プロパティが含まれます。

2025-08-01-preview API バージョン以降、再利用可能なナレッジ ソースによってtargetIndexesが置き換えられ、defaultMaxDocsForRerankerはサポートされなくなりました。 これらの破壊的変更には次のことが必要です:

1. 現在の targetIndexes 構成を取得する
2. 同等のナレッジ ソースを作成する
3. 代わりに knowledgeSources を使用するようにエージェントを更新する targetIndexes
4. 取得をテストするクエリを送信する
5. targetIndexesを使用してクライアントを更新するコードを削除する

現在の構成を取得する

エージェントの定義を取得するには、Knowledge Agents - Get (REST API) の2025-05-01-previewを使用します。

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

応答は、次の例のようになります。 次の手順で使用するために、 indexName、 defaultRerankerThreshold、および defaultIncludeReferenceSourceData の値をコピーします。 defaultMaxDocsForReranker は非推奨であるため、その値は無視できます。

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

ナレッジ ソースを作成する

searchIndexナレッジ ソースを作成するには、ナレッジ ソース - 作成 (REST API) の2025-08-01-previewを使用します。 searchIndexName前にコピーした値に設定します。

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

前の例では、1 つのインデックスを表すナレッジ ソースを作成しますが、複数のインデックスまたはAzure BLOB を対象にすることができます。 詳細については、「 ナレッジ ソースの作成」を参照してください。

エージェントを更新する

targetIndexesをエージェントの定義のknowledgeSourcesに置き換えるには、Knowledge Agents - Create or Update (REST API) の2025-08-01-previewを使用します。 rerankerThresholdとincludeReferenceSourceDataを、以前にコピーした値に設定します。

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

前の例では、定義を更新して 1 つのナレッジ ソースを参照しますが、複数のナレッジ ソースを対象にすることができます。 他のプロパティを使用して、 alwaysQuerySourceなどの取得動作を制御することもできます。 詳細については、「 ナレッジ エージェントの作成」を参照してください。

2025-08-01-preview 更新プログラムの取得をテストする

クエリを使用してエージェントの出力をテストするには、ナレッジ取得 - 取得 (REST API) の2025-08-01-previewを使用します。

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

応答に 200 OK HTTP コードがある場合、エージェントはナレッジ ソースからコンテンツを正常に取得しました。

2025-08-01-preview のコードとクライアントを更新する

移行を完了するには、次のクリーンアップ手順に従います。

• すべての targetIndexes 参照を、構成ファイル、コード、スクリプト、およびテストの knowledgeSources に置き換えます。
• 2025-08-01-previewを使用するようにクライアント呼び出しを更新します。
• 古い図形を使用して作成されたキャッシュされたエージェント定義をクリアまたは再生成します。

バージョン固有の変更

このセクションでは、次の API バージョンにおける破壊的変更と非破壊的変更を扱います。

• 2026-08-01-preview
• 2026-05-01-プレビュー
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview
• 2025-05-01-preview

2026-08-01-preview

2026-08-01-preview バージョンは 2026-05-01-preview に基づいており、Work IQ ナレッジ ソース、オフセットベースのリスト ページング、モデルベースのアクティビティ レコード、MCP サーバーの結果処理、または位置指定で生成されたクライアント呼び出しを使用するアプリケーションの破壊的変更が含まれています。

このバージョンの REST API リファレンス ドキュメント を確認するには、ページの上部にある 2026-08-01-preview API バージョン フィルターを選択します。

2026-05-01-プレビュー

2026-05-01-preview は、以前に永続化されたプロパティを削除せずに、 2025-11-01-preview の上にナレッジ ベース、ナレッジ ソース、および取得機能を追加します。 以前のプレビュー バージョンで作成した既存のナレッジ ベースとナレッジ ソースは引き続き機能します。 このバージョンでは、主に新機能が公開され、プレビューのみの制限がいくつか元に戻されます。

このバージョンの REST API リファレンス ドキュメント を確認するには、ページの上部にある 2026-05-01-preview API バージョン フィルターを選択します。

2026年4月1日

2026-04-01 は、エージェント検索用の最初の安定した API バージョンです。 これは、最小限の抽出取得契約を確立し、プレビュー期のメッセージベースのクエリ計画と応答合成機能を削除します。

このバージョンの REST API リファレンス ドキュメント を確認するには、ページの上部にある 2026-04-01 API バージョン フィルターを選択します。

2025-11-01-preview

このバージョンの REST API リファレンス ドキュメント を確認するには、ページの上部にある 2025-11-01-preview API バージョン フィルターを選択します。

2025-08-01-preview

このバージョンの REST API リファレンス ドキュメント を確認するには、ページの上部にある 2025-08-01-preview API バージョン フィルターを選択します。

2025-05-01-preview

このAPIバージョンでは、エージェント型検索とナレッジエージェントが導入されます。 各エージェント定義には、単一のインデックスと省略可能なプロパティ (targetIndexesやdefaultRerankerThresholdなど) を指定するdefaultIncludeReferenceSourceData配列が必要です。

このバージョンの REST API リファレンス ドキュメント を確認するには、ページの上部にある 2025-05-01-preview API バージョン フィルターを選択します。

関連コンテンツ

• Azure AI 検索 でのエージェンティックリトリーバル
• ナレッジ ベースを作成する
• ナレッジ ベースのクエリを実行する