移行手順は、新しい API バージョンで既存のソリューションを実行するのに役立ちます。 この記事の手順は、API レベルで重大な変更に対処し、アプリが以前と同様に実行されるようにするのに役立ちます。 新しい機能の追加については、 Azure AI 検索。
エージェント検索をサポートするすべてのバージョンでは、破壊的変更が導入されています。 API バージョンの値を保持することで、古いコードを引き続き変更せずに実行できますが、バグ修正、機能強化、および新しい機能の恩恵を受けるには、コードを更新する必要があります。
コードがプレビュー バージョンを対象とする場合は、ユース ケースが 2026-04-01 で完全にサポートされている場合にのみ、最新の安定バージョンに移行することをお勧めします。 回答の合成、非最小限の推論作業、または複数ターンのメッセージに依存する場合は、移行を決定する前に破壊的変更と非破壊的変更を確認してください。 これらの機能はプレビューのままです。
2025-11-01-preview から移行する場合は、2026-04-01 に直接移行できます。 インデックスとコンテンツは変更されません。 必要なのは、ナレッジ ベース スキーマと取得要求の図形のみです。
-
ナレッジ ソースを移行する
-
ナレッジ ベースを移行する
-
取得要求を更新する
-
課金の同意を更新する
-
コードとクライアントを更新する
ナレッジ ソースを移行する
2026-04-01 では、 searchIndex、 azureBlob、 indexedOneLake、 web ナレッジ ソースの種類が一般公開されています。 その他のナレッジ ソースの種類はプレビューのままです。
ナレッジ ソース - Get (REST API) を使用して現在の定義を取得します。
GET {{search-endpoint}}/knowledge-sources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json
応答で、繰り越す内容と削除する内容を特定します。
ナレッジ ソース - 作成または更新 (REST API) を使用して、一意の名前、2026-04-01 API バージョン、および前の手順のプロパティ値を持つ新しいナレッジ ソースを作成します。
次の例は、 searchIndex ナレッジ ソースを示しています。
azureBlob、indexedOneLake、webナレッジ ソースにも同様のパターンを使用します。
PUT {{search-endpoint}}/knowledge-sources/{{new-knowledge-source-name}}?api-version=2026-04-01
api-key: {{api-key}}
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 を保持し、応答生成設定を削除します。 新しいオブジェクトを作成する前に、現在の定義を確認します。
ナレッジ ベース - Get (REST API) を使用して現在の定義を取得します。
GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json
応答で、繰り越す内容と削除する内容を特定します。
knowledgeSources参照に注意してください。 これらを新しいナレッジ ベースに転送します。
存在する場合は、 outputMode、 answerInstructions、および retrievalInstructionsを削除します。 これらのプロパティは、2026-04-01 ではサポートされていません。
ナレッジ ベースで web ナレッジ ソースが使用されている場合は、 modelsを維持します。 Web の取得には、モデルに基づく要約が必要です。 その他のすべてのナレッジ ソースの種類については、 modelsを削除します。
ナレッジ ベース - 作成または更新 (REST API) を使用して、一意の名前、2026-04-01 API バージョン、サポートされているプロパティのみを含む新しいナレッジ ベースを作成します。
PUT {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}?api-version=2026-04-01
api-key: {{api-key}}
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 では、実行中のメッセージ トランスクリプトは保持されません。
クエリを使用してナレッジ ベースの出力をテストするには、2026-04-01 バージョンの ナレッジ取得 - 取得 (REST API) を使用します。
POST {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}/retrieve?api-version=2026-04-01
api-key: {{api-key}}
Content-Type: application/json
{
"intents": [
{
"type": "semantic",
"search": "{{your-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 以降では、エージェント検索課金の同意は、knowledgeRetrievalとは別の専用のsemanticSearch プロパティによって制御されます。これはセマンティック ランカーの課金にのみ適用されるようになりました。
knowledgeRetrieval は管理プレーン プロパティであるため、Search Service REST API ではなく Search Management REST API を使用して設定します。
最新のプレビュー バージョンの サービス - 作成または更新 (REST API) を使用して、検索サービスに knowledgeRetrieval を設定します。
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2026-03-01-preview
Content-Type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"knowledgeRetrieval": "standard"
}
}
有効な値と課金の詳細については、「 エージェント検索の課金を有効または無効にする」を参照してください。
2026-04-01 のコードとクライアントを更新する
移行を完了するには:
2026-04-01 API バージョンを使用するようにクライアント呼び出しを更新します。
コード内のハードコーディングされたナレッジ ベースまたはナレッジ ソース名を更新して、移行中に作成された新しいオブジェクトを参照します。
azureBlobまたはindexedOneLakeナレッジ ソースを移行した場合は、関連付けられているインデックス、インデクサー、データ ソース、またはスキルセットを参照するコードまたはスクリプトを、新しいオブジェクトを指す名前で更新します。
応答の取得を処理するコードを更新します。 応答は、合成された回答ではなく、 activity と referencesを含む抽出接地コンテンツを返します。
新しいオブジェクトが完全に検証され、配置された後にのみ、プレビュー オブジェクトを削除します。
2026-04-01 または 2025-11-01-preview から移行する場合は、2026-05-01-preview に直接移行できます。 これらのバージョンからの要求、応答、および永続化されたオブジェクトには互換性が維持されます。 違いは、追加機能と言語 SDK の名前変更です。
REST 要求で API バージョンを 2026-05-01-preview するように更新します。 SDK クライアントはパッケージの既定の API バージョンを使用するため、明示的な serviceVersion 引数を渡す必要はありません。 代わりに、2026-05-01-preview SDK パッケージにアップグレードします。
Pythonまたは JavaScript SDK を使用する場合は、取得クライアントを KnowledgeBaseRetrievalClient に更新し、レガシ retrieve(...) の代わりに retrieveKnowledge(...) を呼び出します。 完全な SDK シェイプ マッピングについては、 2026-05-01-preview のコードとクライアントの更新 に関する記事を参照してください。
必要に応じて、鮮度を考慮した取得、ソースごとのドキュメント上限と最終結果のドキュメント上限、保持された取得の既定値、ナレッジ ベースの CORS、取得応答内の Purview の秘密度ラベル メタデータなどの新しい 2026-05-01-preview 機能を採用できます。 既存のソリューションを動作させ続けるために、これらの機能は必要ありません。
2026-05-01-preview のコードとクライアントを更新する
2026-05-01-preview 言語 SDK では、サポートされている言語全体でコードシェイプの変更が導入されています。
| Language |
移行の更新情報 |
| Python |
KnowledgeBaseRetrievalClient(endpoint=..., credential=..., knowledge_base_name=...)として取得クライアントを作成します。
KnowledgeRetrievalLowReasoningEffort()などの推論作業インスタンスを構築し、ナレッジ ベースにoutput_mode="answerSynthesis"文字列を渡すか、要求を取得します。
AzureOpenAIVectorizerParameters(resource_url=...) エンドポイントではなくリソース ルート エンドポイントを使用し、resource_uri（/openai/v1 から名称変更）を渡します。 |
| .NET |
new KnowledgeBaseRetrievalClient(endpoint, knowledgeBaseName, credential)として取得クライアントを作成し、AzureKeyCredentialまたはトークンの資格情報を渡します。 キーベースの Azure OpenAI モデルをナレッジ ベースにアタッチするには、モデル API キーを AzureOpenAIVectorizerParameters.ApiKey に設定します。 |
| Java |
KnowledgeBaseRetrievalClientBuilderを使用して取得クライアントを作成し、結果をKnowledgeBaseRetrievalResultとして読み取ります。
KnowledgeBaseRetrievalOptionsでは、setMessages(...)、setIntents(...)、setRetrievalReasoningEffort、setOutputMode、およびsetMaxOutputSizeと共にsetMaxOutputDocumentsが公開されるようになりました。そのため、セマンティック意図の回避策なしでメッセージ ベースの取得と応答の合成作業が行われます。
KnowledgeBase は、 setOutputMode、 setRetrievalReasoningEffort、 setRetrievalInstructions、 setAnswerInstructions、および setCorsOptionsを追加します。
SearchIndexKnowledgeSourceParams は、 setAlwaysQuerySource、 setFailOnError、 setMaxOutputDocuments、および setEnableImageServingを追加します。 |
| JavaScript と TypeScript |
KnowledgeRetrievalClient.retrieve({ intents: [{ type: "semantic", search: query }] }) を使用してください。 前の retrieveKnowledge(...) メソッドは、 retrieve(...)を優先して削除されます。 |
クライアント図形を更新した後、インデックスの作成、ドキュメントのアップロード、ナレッジ ソースの作成、ナレッジ ベースの作成、取得要求の発行、リソースのクリーンアップを行って、移行をエンドツーエンドで確認するフル フローを実行します。
2025-08-01-preview から移行する場合、"ナレッジ エージェント" の名前が "ナレッジ ベース" に変更され、オブジェクト定義内の異なるオブジェクトとレベルに複数のプロパティが再配置されます。
-
searchIndex ナレッジ ソースを更新する
-
azureBlob ナレッジ ソースを更新する
-
ナレッジ エージェントをナレッジ ベースに置き換える
-
取得要求を更新し、更新をテストするクエリを送信する
-
クライアント コードを更新する
searchIndex ナレッジ ソースを更新する
この手順では、新しい 2025-11-01-preview searchIndex ナレッジ ソースを、以前の 2025-08-01 バージョンと同じ機能レベルで作成します。 基になるインデックス自体に更新は必要ありません。
すべてのナレッジ ソースを名前で一覧表示して、ナレッジ ソースを検索します。
### List all knowledge sources by name
GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
api-key: {{api-key}}
Content-Type: application/json
既存のプロパティを 確認する現在の定義を取得します。
### Get a specific knowledge source
GET {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
api-key: {{api-key}}
Content-Type: application/json
応答は次の例のようになります。
{
"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
}
移行の基礎として 、ナレッジ ソースの作成 要求を作成します。
08-01-preview JSON から始めます。
POST {{url}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
api-key: {{key}}
Content-Type: application/json
{
"name": "search-index-ks",
"kind": "searchIndex",
"description": "A sample search index knowledge source",
"encryptionKey": null,
"searchIndexParameters": {
"searchIndexName": "my-search-index",
"sourceDataSelect": "id, page_chunk, page_number"
}
}
2025-11-01-preview 移行作業のために必要な次の更新を行います。
更新プログラムを確認し、オブジェクトを作成する要求を送信します。
PUT {{url}}/knowledge-sources/search-index-ks-11-01?api-version=2025-11-01-preview
api-key: {{key}}
Content-Type: application/json
{
"name": "search-index-ks-11-01",
"kind": "searchIndex",
"description": "knowledge source migrated to 2025-11-01-preview",
"encryptionKey": null,
"searchIndexParameters": {
"searchIndexName": "my-search-index",
"sourceDataFields": [
{ "name": "id" }, { "name": "page_chunk" }, { "name": "page_number" }
]
}
}
2025-11-01-preview の正しいプロパティ仕様を使用して、以前のバージョンと下位互換性のある移行された searchIndex ナレッジ ソースが作成されました。
応答には、新しいオブジェクトの完全な定義が含まれます。 このナレッジ ソースの種類で使用できる新しいプロパティの詳細については、「 検索インデックスのナレッジ ソースを作成する方法」を参照してください。
azureBlob ナレッジ ソースを更新する
この手順では、新しい 2025-11-01-preview azureBlob ナレッジ ソースを、以前の 2025-08-01 バージョンと同じ機能レベルで作成します。 生成されたオブジェクトの新しいセット (データ ソース、スキルセット、インデクサー、インデックス) が作成されます。
すべてのナレッジ ソースを名前で一覧表示して、ナレッジ ソースを検索します。
### List all knowledge sources by name
GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
api-key: {{api-key}}
Content-Type: application/json
既存のプロパティを 確認する現在の定義を取得します。
### Get a specific knowledge source
GET {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
api-key: {{api-key}}
Content-Type: application/json
ワークフローにモデルが含まれている場合、応答は次の例のようになります。 応答には、生成されたオブジェクトの名前が含まれていることに注意してください。 これらのオブジェクトはナレッジ ソースから完全に独立しており、ナレッジ ソースを更新または削除しても動作し続けます。
{
"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"
}
}
}
移行の基礎として 、ナレッジ ソースの作成 要求を作成します。
08-01-preview JSON から始めます。
POST {{url}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
api-key: {{key}}
Content-Type: application/json
{
"name": "azure-blob-ks",
"kind": "azureBlob",
"description": "A sample azure blob knowledge source.",
"encryptionKey": null,
"azureBlobParameters": {
"connectionString": "<redacted>",
"containerName": "blobcontainer",
"folderPath": null,
"disableImageVerbalization": false,
"identity": null,
"embeddingModel": {
"name": "embedding-model",
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<redacted>",
"deploymentId": "text-embedding-3-large",
"apiKey": "<redacted>",
"modelName": "text-embedding-3-large",
"authIdentity": null
},
"customWebApiParameters": null,
"aiServicesVisionParameters": null,
"amlParameters": null
},
"chatCompletionModel": null,
"ingestionSchedule": null
}
}
2025-11-01-preview 移行作業のために必要な次の更新を行います。
更新プログラムを確認し、オブジェクトを作成する要求を送信します。 インデクサー パイプライン用に新しく生成されたオブジェクトが作成されます。
PUT {{url}}/knowledge-sources/azure-blob-ks-11-01?api-version=2025-11-01-preview
api-key: {{key}}
Content-Type: application/json
{
"name": "azure-blob-ks",
"kind": "azureBlob",
"description": "A sample azure blob knowledge source",
"encryptionKey": null,
"azureBlobParameters": {
"connectionString": "{{blob-connection-string}}",
"containerName": "blobcontainer",
"folderPath": null,
"ingestionParameters": {
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"deploymentId": "text-embedding-3-large",
"modelName": "text-embedding-3-large",
"resourceUri": "{{aoai-endpoint}}",
"apiKey": "{{aoai-key}}"
}
},
"chatCompletionModel": null,
"disableImageVerbalization": false,
"ingestionSchedule": null,
"contentExtractionMode": "minimal"
}
}
}
2025-11-01-preview の正しいプロパティ仕様を使用して、以前のバージョンと下位互換性のある移行された azureBlob ナレッジ ソースが作成されました。
応答には、新しいオブジェクトの完全な定義が含まれます。 このナレッジ ソースの種類で使用できる新しいプロパティの詳細については、「 BLOB ナレッジ ソースの作成」を参照してください。
ナレッジ エージェントをナレッジ ベースに置き換える
ナレッジ ベースにはナレッジ ソースが必要です。 開始する前に、2025-11-01-preview を対象とするナレッジ ソースがあることを確認してください。
既存のプロパティを 確認する現在の定義を取得します。
### Get a knowledge agent by name
GET {{search-endpoint}}/agents/earth-at-night?api-version=2025-08-01-preview
api-key: {{api-key}}
Content-Type: application/json
応答は次の例のようになります。
{
"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
}
}
移行の基礎として ナレッジ ベースの作成 要求を作成します。
08-01-preview JSON から始めます。
PUT {{url}}/knowledgebases/earth-at-night?api-version=2025-08-01-preview HTTP/1.1
api-key: {{key}}
Content-Type: application/json
{
"name": "earth-at-night",
"description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.",
"retrievalInstructions": null,
"encryptionKey": null,
"knowledgeSources": [
{
"name": "earth-at-night",
"alwaysQuerySource": null,
"includeReferences": null,
"includeReferenceSourceData": null,
"maxSubQueries": null,
"rerankerThreshold": 2.5
}
],
"models": [
{
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<redacted>",
"apiKey": "<redacted>",
"deploymentId": "gpt-5-mini",
"modelName": "gpt-5-mini"
}
}
],
"outputConfiguration": {
"modality": "answerSynthesis"
}
}
2025-11-01-preview 移行作業のために必要な次の更新を行います。
エンドポイントを置き換えます: /knowledgebases/{{your-object-name}}。 ナレッジ ベースに一意の名前を付けます。
API のバージョンを 2025-11-01-preview に変更します。
requestLimitsを削除します。
maxRuntimeInSecondsプロパティとmaxOutputSizeプロパティが取得要求オブジェクトで直接指定されるようになりました。
knowledgeSourcesの更新:
modelsの変更はありません。
outputConfigurationの更新:
outputConfigurationをoutputModeに置き換えます。
attemptFastPathを削除します。 存在しなくなりました。 同等の動作は、retrievalReasoningEffort を最小値に設定することで実現されます（取得推論の労力を設定する (プレビュー) を参照）。
モダリティを answerSynthesis に設定している場合は、取得プロセスの負荷を低 (既定) または中に設定していることを確認します。
2025-11-01-preview azureBlob ナレッジ ソースを作成するための要件として、 ingestionParameters を追加します。
更新プログラムを確認し、オブジェクトを作成する要求を送信します。 インデクサー パイプライン用に新しく生成されたオブジェクトが作成されます。
PUT {{url}}/knowledgebases/earth-at-night-11-01?api-version={{api-version}}
api-key: {{key}}
Content-Type: application/json
{
"name": "earth-at-night-11-01",
"description": "A sample knowledge base at the same functional level as the previous knowledge agent.",
"retrievalInstructions": null,
"encryptionKey": null,
"knowledgeSources": [
{
"name": "earth-at-night-ks"
}
],
"models": [
{
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<redacted>",
"apiKey": "<redacted>",
"deploymentId": "gpt-5-mini",
"modelName": "gpt-5-mini"
}
}
],
"retrievalReasoningEffort": null,
"outputMode": "answerSynthesis",
"answerInstructions": "Provide a concise and accurate answer based on the retrieved information.",
}
ナレッジ エージェントではなくナレッジ ベースが作成され、オブジェクトは以前のバージョンと下位互換性があります。
応答には、新しいオブジェクトの完全な定義が含まれます。 ナレッジ ベースで使用できる新しいプロパティの詳細については、「ナレッジ ベースを作成する方法」を参照してください。
2025-11-01-preview 更新プログラムの取得を更新してテストする
取得要求は 2025-11-01-preview で変更され、LLM 処理を最小限に抑える単純な要求など、より多くの図形がサポートされます。 このプレビューでの取得の詳細については、「 ナレッジ ベースを使用したデータの取得」を参照してください。 このセクションでは、コードを更新する方法について説明します。
/agents/retrieve エンドポイントを /knowledgebases/retrieve に変更します。
API のバージョンを 2025-11-01-preview に変更します。
messagesまたは low retrievalReasoningEffort を使用している場合は、mediumを変更する必要はありません。 メッセージをintentに置き換えてください（minimal 推論を使用する場合。取得の推論の強度を設定する（プレビュー）を参照）。
エージェントから削除されたすべてのプロパティ (knowledgeSourceParams、rerankerThreshold、alwaysQuerySource、includeReferenceSourceData) を含むようにincludeReferencesを変更します。
retrievalReasoningEffortを使用していた場合は、minimumにattemptFastPathを追加します。
maxSubQueriesを使用していた場合は、存在しなくなります。
retrievalReasoningEffort設定を使用して、サブクエリ処理を指定します (取得理由の設定 (プレビュー) を参照してください)。
クエリを使用してナレッジ ベースの出力をテストするには、 Knowledge Retrieve - Retrieve (REST API) の 2025-11-01-preview を使用します。
### Send a query to the knowledge base
POST {{url}}/knowledgebases/earth-at-night-11-01/retrieve?api-version=2025-11-01-preview
api-key: {{key}}
Content-Type: application/json
{
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "What are some light sources on the ocean at night" }
]
}
],
"includeActivity": true,
"retrievalReasoningEffort": { "kind": "medium" },
"outputMode": "answerSynthesis",
"maxRuntimeInSeconds": 30,
"maxOutputSize": 6000
}
応答に 200 OK HTTP コードがある場合、ナレッジ ベースはナレッジ ソースからコンテンツを正常に取得しました。
2025-11-01-preview のコードとクライアントを更新する
移行を完了するには、次のクリーンアップ手順に従います。
BLOB ナレッジ ソースの場合のみ、新しいインデックスを使用するようにクライアントを更新します。 インデクサーを実行するコードまたはスクリプトがある場合、またはデータ ソース、インデックス、またはスキルセットを参照している場合は、必ず新しいオブジェクトへの参照を更新してください。
すべてのエージェント参照を、構成ファイル、コード、スクリプト、およびテストの knowledgeBases に置き換えます。
2025-11-01-preview を使用するようにクライアント呼び出しを更新します。
古い図形を使用して作成されたキャッシュされた定義をクリアまたは再生成します。
2025-05-01-preview を使用してナレッジ エージェントを作成した場合、エージェントの定義にはインラインtargetIndexes配列とオプションのdefaultMaxDocsForReranker プロパティが含まれます。
2025-08-01-preview 以降では、再利用可能なナレッジ ソースによってtargetIndexesが置き換えられ、defaultMaxDocsForRerankerはサポートされなくなりました。 これらの破壊的変更には次のことが必要です:
-
現在の
targetIndexes 構成を取得する
-
同等のナレッジ ソースを作成する
-
代わりに
knowledgeSources を使用するようにエージェントを更新する targetIndexes
-
取得をテストするクエリを送信する
-
targetIndexesを使用してクライアントを更新するコードを削除する
現在の構成を取得する
エージェントの定義を取得するには、 Knowledge Agents - Get (REST API) の 2025-05-01-preview を使用します。
@search-url = <YourSearchServiceUrl>
@agent-name = <YourAgentName>
@api-key = <YourApiKey>
### Get agent definition
GET https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview HTTP/1.1
api-key: {{api-key}}
応答は、次の例のようになります。 次の手順で使用するために、 indexName、 defaultRerankerThreshold、および defaultIncludeReferenceSourceData の値をコピーします。
defaultMaxDocsForReranker は非推奨であるため、その値は無視できます。
{
"@odata.etag": "0x1234568AE7E58A1",
"name": "my-knowledge-agent",
"description": "My description of the agent",
"targetIndexes": [
{
"indexName": "my-index", // Copy this value
"defaultRerankerThreshold": 2.5, // Copy this value
"defaultIncludeReferenceSourceData": true, // Copy this value
"defaultMaxDocsForReranker": 100
}
],
... // Redacted for brevity
}
ナレッジ ソースを作成する
searchIndexナレッジ ソースを作成するには、ナレッジ ソース - 作成 (REST API) の 2025-08-01-preview を使用します。
searchIndexName前にコピーした値に設定します。
@source-name = <YourSourceName>
### Create a knowledge source
PUT https://{{search-url}}/knowledgeSources/{{source-name}}?api-version=2025-08-01-preview HTTP/1.1
Content-Type: application/json
api-key: {{api-key}}
{
"name": "{{source-name}}",
"description": "My description of the knowledge source",
"kind": "searchIndex",
"searchIndexParameters": {
"searchIndexName": "my-index" // Use the previous value
}
}
この例では、1 つのインデックスを表すナレッジ ソースを作成しますが、複数のインデックスまたはAzure BLOB を対象にすることができます。 詳細については、「 ナレッジ ソースの作成」を参照してください。
エージェントを更新する
targetIndexesをエージェントの定義のknowledgeSourcesに置き換えるには、Knowledge Agents - Create or Update (REST API) の 2025-08-01-preview を使用します。
rerankerThresholdとincludeReferenceSourceDataを、以前にコピーした値に設定します。
### Replace targetIndexes with knowledgeSources
POST https://{{search-url}}/agents/{{agent-name}}?api-version=2025-08-01-preview HTTP/1.1
Content-Type: application/json
api-key: {{api-key}}
{
"name": "{{agent-name}}",
"knowledgeSources": [
{
"name": "{{source-name}}",
"rerankerThreshold": 2.5, // Use the previous value
"includeReferenceSourceData": true // Use the previous value
}
]
}
この例では、1 つのナレッジ ソースを参照するように定義を更新しますが、複数のナレッジ ソースを対象にすることができます。 他のプロパティを使用して、 alwaysQuerySourceなどの取得動作を制御することもできます。 詳細については、「 ナレッジ エージェントの作成」を参照してください。
2025-08-01-preview 更新プログラムの取得をテストする
クエリを使用してエージェントの出力をテストするには、 Knowledge Retrieve - Retrieve (REST API) の 2025-08-01-preview を使用します。
### Send a query to the agent
POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview HTTP/1.1
Content-Type: application/json
api-key: {{api-key}}
{
"messages": [
{
"role": "user",
"content" : [
{
"text": "<YourQueryText>",
"type": "text"
}
]
}
]
}
応答に 200 OK HTTP コードがある場合、エージェントはナレッジ ソースからコンテンツを正常に取得しました。
2025-08-01-preview のコードとクライアントを更新する
移行を完了するには、次のクリーンアップ手順に従います。
- すべての
targetIndexes 参照を、構成ファイル、コード、スクリプト、およびテストの knowledgeSources に置き換えます。
- 2025-08-01-preview を使用するようにクライアント呼び出しを更新します。
- 古い図形を使用して作成されたキャッシュされたエージェント定義をクリアまたは再生成します。
2026-04-01 は、エージェント検索用の最初の安定した API バージョンです。 これは、最小限の抽出取得契約を確立し、プレビュー期のメッセージベースのクエリ計画と応答合成機能を削除します。
この REST API バージョンでは、エージェント的な検索とナレッジエージェントが導入されています。 各エージェント定義には、単一のインデックスと省略可能なプロパティ (targetIndexesやdefaultRerankerThresholdなど) を指定するdefaultIncludeReferenceSourceData配列が必要です。