Knowledge Retrieval - Retrieve

サービス:: Search Service

API バージョン:: 2025-08-01-preview

KnowledgeAgent は、バッキングストアから関連データを取得します。

POST {endpoint}/agents('{agentName}')/retrieve?api-version=2025-08-01-preview

URI パラメーター

名前	/	必須	型	説明
agentName	path	True	string	エージェントの名前。
endpoint	path	True	string (url)	検索サービスのエンドポイント URL。
api-version	query	True	string	クライアント API バージョン。

要求ヘッダー

名前	必須	型	説明
x-ms-client-request-id		string (uuid)	デバッグを支援するためにリクエストとともに送信されたトラッキング ID。
x-ms-query-source-authorization		string	クエリが実行されているユーザーを識別するトークン。このトークンは、ドキュメントにセキュリティ制限を適用するために使用されます。

要求本文

名前	必須	型	説明
messages	True	KnowledgeAgentMessage[]	自然言語メッセージスタイルオブジェクト。
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

応答

名前	型	説明
200 OK	KnowledgeAgentRetrievalResponse	取得応答は正常に返されます。
Other Status Codes	ErrorResponse	エラー応答。

例

KnowledgeAgentRetrieve

要求のサンプル

HTTP

POST https://previewexampleservice.search.windows.net/agents('agent-preview-test')/retrieve?api-version=2025-08-01-preview



{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "text": "hello world",
          "type": "text"
        }
      ]
    }
  ],
  "knowledgeSourceParams": [
    {
      "filterAddOn": "foo eq bar",
      "knowledgeSourceName": "ks-preview-test",
      "kind": "searchIndex"
    }
  ]
}

応答のサンプル

状態コード:: 200

{
  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "[{...}]"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "modelQueryPlanning",
      "id": 0,
      "inputTokens": 11,
      "outputTokens": 22,
      "elapsedMs": 10
    },
    {
      "type": "searchIndex",
      "id": 1,
      "knowledgeSourceName": "ks-preview-test",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "hello world",
        "filter": "foo eq bar"
      }
    },
    {
      "type": "searchIndex",
      "id": 2,
      "knowledgeSourceName": "ks-preview-test",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "hello world two",
        "filter": "foo eq bar"
      }
    },
    {
      "type": "semanticReranker",
      "id": 3,
      "inputTokens": 74,
      "elapsedMs": 0
    }
  ],
  "references": [
    {
      "type": "searchIndex",
      "id": "83dd7d40",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey1",
        "title": "high_doc",
        "content": "hello world"
      },
      "rerankerScore": 3.5,
      "docKey": "myDocKey1"
    },
    {
      "type": "searchIndex",
      "id": "83dd7d41",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey2",
        "title": "low_doc",
        "content": "goodbye world"
      },
      "rerankerScore": 2.7,
      "docKey": "myDocKey2"
    }
  ]
}

定義

名前	説明
ErrorAdditionalInfo	リソース管理エラーの追加情報。
ErrorDetail	エラーの詳細。
ErrorResponse	エラー応答
Image
KnowledgeAgentAzureBlobActivityArguments	Azure BLOB 取得アクティビティが実行された引数を表します。
KnowledgeAgentAzureBlobActivityRecord	Azure BLOB 取得アクティビティレコードを表します。
KnowledgeAgentAzureBlobReference	Azure Blob Storage ドキュメント参照を表します。
KnowledgeAgentMessage	自然言語メッセージスタイルオブジェクト。
KnowledgeAgentMessageContentType	メッセージコンテンツの種類。
KnowledgeAgentMessageImageContent	テキストメッセージの種類。
KnowledgeAgentMessageTextContent	テキストメッセージの種類。
KnowledgeAgentModelAnswerSynthesisActivityRecord	LLM 回答合成アクティビティレコードを表します。
KnowledgeAgentModelQueryPlanningActivityRecord	LLM クエリ計画アクティビティレコードを表します。
KnowledgeAgentRetrievalRequest	取得要求の入力コントラクト。
KnowledgeAgentRetrievalResponse	取得応答の出力コントラクト。
KnowledgeAgentSearchIndexActivityArguments	検索インデックス取得アクティビティが実行された引数を表します。
KnowledgeAgentSearchIndexActivityRecord	検索索引取得アクティビティー・レコードを表します。
KnowledgeAgentSearchIndexReference	Azure Search ドキュメント参照を表します。
KnowledgeAgentSemanticRerankerActivityRecord	セマンティックランカーアクティビティレコードを表します。
KnowledgeSourceKind	知識源の種類。
SearchIndexKnowledgeSourceParams	検索インデックスナレッジソースのランタイムパラメータを指定します

ErrorAdditionalInfo

Object

リソース管理エラーの追加情報。

名前	型	説明
info	object	追加情報。
type	string	追加情報の種類。

ErrorDetail

Object

エラーの詳細。

名前	型	説明
additionalInfo	ErrorAdditionalInfo[]	エラーの追加情報。
code	string	エラーコード。
details	ErrorDetail[]	エラーの詳細です。
message	string	エラーメッセージ。
target	string	エラーターゲット。

ErrorResponse

Object

エラー応答

名前	型	説明
error	ErrorDetail	エラーオブジェクト。

Image

Object

名前	型	説明
url	string (uri)	イメージの URL。

KnowledgeAgentAzureBlobActivityArguments

Object

Azure BLOB 取得アクティビティが実行された引数を表します。

名前	型	説明
search	string	BLOB コンテンツのクエリに使用される検索文字列。

KnowledgeAgentAzureBlobActivityRecord

Object

Azure BLOB 取得アクティビティレコードを表します。

名前	型	説明
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	取得アクティビティの Azure BLOB 引数。
count	integer (int32)	リランカーのしきい値を超えるのに十分な関連性を持つ取得されたドキュメントの数。
elapsedMs	integer (int32)	取得アクティビティの経過時間(ミリ秒単位)。
id	integer (int32)	アクティビティレコードの ID。
knowledgeSourceName	string	取得アクティビティのナレッジソース。
queryTime	string (date-time)	この取得アクティビティのクエリ時間。
type	string: azureBlob	アクティビティレコードのタイプ。

KnowledgeAgentAzureBlobReference

Object

Azure Blob Storage ドキュメント参照を表します。

名前	型	説明
activitySource	integer (int32)	参照のソース・アクティビティー ID。
blobUrl	string	参照の BLOB URL。
id	string	参照の ID。
rerankerScore	number (float)	ドキュメント参照のリランカースコア。
sourceData	object
type	string: azureBlob	参照のタイプ。

KnowledgeAgentMessage

Object

自然言語メッセージスタイルオブジェクト。

名前	型	説明
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	メッセージコンテンツのタイプを指定します。
role	string	ツール応答の役割。

KnowledgeAgentMessageContentType

列挙

メッセージコンテンツの種類。

値	説明
text	テキストメッセージコンテンツの種類。
image	画像メッセージコンテンツの種類。

KnowledgeAgentMessageImageContent

Object

テキストメッセージの種類。

名前	型	説明
image	Image
type	string: image	メッセージの種類

KnowledgeAgentMessageTextContent

Object

テキストメッセージの種類。

名前	型	説明
text	string
type	string: text	メッセージの種類

KnowledgeAgentModelAnswerSynthesisActivityRecord

Object

LLM 回答合成アクティビティレコードを表します。

名前	型	説明
elapsedMs	integer (int32)	取得アクティビティの経過時間(ミリ秒単位)。
id	integer (int32)	アクティビティレコードの ID。
inputTokens	integer (int32)	LLM 回答合成アクティビティの入力トークンの数。
outputTokens	integer (int32)	LLM 回答合成アクティビティの出力トークンの数。
type	string: modelAnswerSynthesis	アクティビティレコードのタイプ。

KnowledgeAgentModelQueryPlanningActivityRecord

Object

LLM クエリ計画アクティビティレコードを表します。

名前	型	説明
elapsedMs	integer (int32)	取得アクティビティの経過時間(ミリ秒単位)。
id	integer (int32)	アクティビティレコードの ID。
inputTokens	integer (int32)	LLM クエリ計画アクティビティの入力トークンの数。
outputTokens	integer (int32)	LLM クエリ計画アクティビティの出力トークンの数。
type	string: modelQueryPlanning	アクティビティレコードのタイプ。

KnowledgeAgentRetrievalRequest

Object

取得要求の入力コントラクト。

名前	型	説明
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	自然言語メッセージスタイルオブジェクト。

KnowledgeAgentRetrievalResponse

Object

取得応答の出力コントラクト。

名前	型	説明
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	進捗状況と請求への影響を追跡するためのアクティビティレコード。
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	応答で使用される取得データの参照。
response	KnowledgeAgentMessage[]	自然言語メッセージスタイルオブジェクト。

KnowledgeAgentSearchIndexActivityArguments

Object

検索インデックス取得アクティビティが実行された引数を表します。

名前	型	説明
filter	string	フィルター文字列。
search	string	検索インデックスを問い合わせるための検索文字列。

KnowledgeAgentSearchIndexActivityRecord

Object

検索索引取得アクティビティー・レコードを表します。

名前	型	説明
count	integer (int32)	リランカーのしきい値を超えるのに十分な関連性を持つ取得されたドキュメントの数。
elapsedMs	integer (int32)	取得アクティビティの経過時間(ミリ秒単位)。
id	integer (int32)	アクティビティレコードの ID。
knowledgeSourceName	string	取得アクティビティのナレッジソース。
queryTime	string (date-time)	この取得アクティビティのクエリ時間。
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	検索アクティビティの検索インデックス引数。
type	string: searchIndex	アクティビティレコードのタイプ。

KnowledgeAgentSearchIndexReference

Object

Azure Search ドキュメント参照を表します。

名前	型	説明
activitySource	integer (int32)	参照のソース・アクティビティー ID。
docKey	string	参照のドキュメントキー。
id	string	参照の ID。
rerankerScore	number (float)	ドキュメント参照のリランカースコア。
sourceData	object
type	string: searchIndex	参照のタイプ。

KnowledgeAgentSemanticRerankerActivityRecord

Object

セマンティックランカーアクティビティレコードを表します。

名前	型	説明
elapsedMs	integer (int32)	取得アクティビティの経過時間(ミリ秒単位)。
id	integer (int32)	アクティビティレコードの ID。
inputTokens	integer (int32)	セマンティックランカーアクティビティの入力トークンの数。
type	string: semanticReranker	アクティビティレコードのタイプ。

KnowledgeSourceKind

列挙

知識源の種類。

値	説明
searchIndex	検索インデックスからデータを読み取るナレッジソース。
azureBlob	Azure Blob Storage から検索インデックスにデータを読み取り、取り込むナレッジソース。

SearchIndexKnowledgeSourceParams

Object

検索インデックスナレッジソースのランタイムパラメータを指定します

名前	型	説明
filterAddOn	string	インデックスに適用されるフィルター条件 (例: 'State eq VA')。
kind	string: searchIndex	ナレッジソースのタイプ。
knowledgeSourceName	string	パラメータが適用されるインデックスの名前。