Knowledge Retrieval - Retrieve

Service:: Search Service

Version d'API:: 2025-08-01-preview

KnowledgeAgent récupère les données pertinentes à partir des magasins de sauvegarde.

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

Paramètres URI

Nom	Dans	Obligatoire	Type	Description
agentName	path	True	string	Nom de l’agent.
endpoint	path	True	string (url)	URL du point de terminaison du service de recherche.
api-version	query	True	string	Version de l’API client.

En-tête de la demande

Nom	Obligatoire	Type	Description
x-ms-client-request-id		string (uuid)	ID de suivi envoyé avec la demande pour aider au débogage.
x-ms-query-source-authorization		string	Jeton identifiant l’utilisateur pour lequel la requête est exécutée. Ce jeton est utilisé pour appliquer des restrictions de sécurité sur les documents.

Corps de la demande

Nom	Obligatoire	Type	Description
messages	True	KnowledgeAgentMessage[]	Objet de style de message en langage naturel.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

Réponses

Nom	Type	Description
200 OK	KnowledgeAgentRetrievalResponse	La réponse de récupération est renvoyée avec succès.
Other Status Codes	ErrorResponse	Réponse d’erreur.

Exemples

KnowledgeAgentRetrieve

Exemple de requête

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

Exemple de réponse

Code d’état:: 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"
    }
  ]
}

Définitions

Nom	Description
ErrorAdditionalInfo	Informations supplémentaires sur l’erreur de gestion des ressources.
ErrorDetail	Détail de l’erreur.
ErrorResponse	Réponse d’erreur
Image
KnowledgeAgentAzureBlobActivityArguments	Représente les arguments avec lesquels l’activité d’extraction d’objets blob Azure a été exécutée.
KnowledgeAgentAzureBlobActivityRecord	Représente un enregistrement d’activité d’extraction d’objets blob Azure.
KnowledgeAgentAzureBlobReference	Représente une référence de document de référence sur le stockage Blob Azure.
KnowledgeAgentMessage	Objet de style de message en langage naturel.
KnowledgeAgentMessageContentType	Le type de contenu du message.
KnowledgeAgentMessageImageContent	Type de SMS.
KnowledgeAgentMessageTextContent	Type de SMS.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Représente un enregistrement d’activité de synthèse de réponse LLM.
KnowledgeAgentModelQueryPlanningActivityRecord	Représente un enregistrement d’activité de planification de requête LLM.
KnowledgeAgentRetrievalRequest	Contrat d’entrée pour la demande d’extraction.
KnowledgeAgentRetrievalResponse	Contrat de sortie pour la réponse d’extraction.
KnowledgeAgentSearchIndexActivityArguments	Représente les arguments avec lesquels l’activité d’extraction d’index de recherche a été exécutée.
KnowledgeAgentSearchIndexActivityRecord	Représente un enregistrement d’activité d’extraction d’index de recherche.
KnowledgeAgentSearchIndexReference	Représente une référence de document Recherche Azure.
KnowledgeAgentSemanticRerankerActivityRecord	Représente un enregistrement d’activité de ranker sémantique.
KnowledgeSourceKind	Le type de source de connaissance.
SearchIndexKnowledgeSourceParams	Spécifie les paramètres d’exécution d’une source de connaissances d’index de recherche

ErrorAdditionalInfo

Objet

Informations supplémentaires sur l’erreur de gestion des ressources.

Nom	Type	Description
info	object	Informations supplémentaires.
type	string	Type d’informations supplémentaire.

ErrorDetail

Objet

Détail de l’erreur.

Nom	Type	Description
additionalInfo	ErrorAdditionalInfo[]	Informations supplémentaires sur l’erreur.
code	string	Code d'erreur.
details	ErrorDetail[]	Détails de l’erreur.
message	string	Message d’erreur.
target	string	Cible d’erreur.

ErrorResponse

Objet

Réponse d’erreur

Nom	Type	Description
error	ErrorDetail	Objet d’erreur.

Image

Objet

Nom	Type	Description
url	string (uri)	L’URL de l’image.

KnowledgeAgentAzureBlobActivityArguments

Objet

Représente les arguments avec lesquels l’activité d’extraction d’objets blob Azure a été exécutée.

Nom	Type	Description
search	string	Chaîne de recherche utilisée pour interroger le contenu d’un objet blob.

KnowledgeAgentAzureBlobActivityRecord

Objet

Représente un enregistrement d’activité d’extraction d’objets blob Azure.

Nom	Type	Description
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Les arguments blob Azure pour l’activité d’extraction.
count	integer (int32)	Le nombre de documents récupérés qui étaient suffisamment pertinents pour passer le seuil de reranker.
elapsedMs	integer (int32)	Temps écoulé en millisecondes pour l’activité d’extraction.
id	integer (int32)	ID de l’enregistrement d’activité.
knowledgeSourceName	string	Source de connaissances pour l’activité d’extraction.
queryTime	string (date-time)	Temps de requête pour cette activité d’extraction.
type	string: azureBlob	Type d’enregistrement d’activité.

KnowledgeAgentAzureBlobReference

Objet

Représente une référence de document de référence sur le stockage Blob Azure.

Nom	Type	Description
activitySource	integer (int32)	ID de l’activité source de la référence.
blobUrl	string	URL de l’objet blob de référence.
id	string	ID de la référence.
rerankerScore	number (float)	Le score du reranker pour la référence du document.
sourceData	object
type	string: azureBlob	Type de référence.

KnowledgeAgentMessage

Objet

Objet de style de message en langage naturel.

Nom	Type	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Spécifie le type de contenu du message.
role	string	Le rôle de la réponse de l’outil.

KnowledgeAgentMessageContentType

Énumération

Le type de contenu du message.

Valeur	Description
text	Type de contenu de message texte.
image	Type de contenu de message d’image.

KnowledgeAgentMessageImageContent

Objet

Type de SMS.

Nom	Type	Description
image	Image
type	string: image	Le type du message

KnowledgeAgentMessageTextContent

Objet

Type de SMS.

Nom	Type	Description
text	string
type	string: text	Le type du message

KnowledgeAgentModelAnswerSynthesisActivityRecord

Objet

Représente un enregistrement d’activité de synthèse de réponse LLM.

Nom	Type	Description
elapsedMs	integer (int32)	Temps écoulé en millisecondes pour l’activité d’extraction.
id	integer (int32)	ID de l’enregistrement d’activité.
inputTokens	integer (int32)	Nombre de jetons d’entrée pour l’activité de synthèse de réponse LLM.
outputTokens	integer (int32)	Nombre de jetons de sortie pour l’activité de synthèse de réponse LLM.
type	string: modelAnswerSynthesis	Type d’enregistrement d’activité.

KnowledgeAgentModelQueryPlanningActivityRecord

Objet

Représente un enregistrement d’activité de planification de requête LLM.

Nom	Type	Description
elapsedMs	integer (int32)	Temps écoulé en millisecondes pour l’activité d’extraction.
id	integer (int32)	ID de l’enregistrement d’activité.
inputTokens	integer (int32)	Nombre de jetons d’entrée pour l’activité de planification de requête LLM.
outputTokens	integer (int32)	Nombre de jetons de sortie pour l’activité de planification de requête LLM.
type	string: modelQueryPlanning	Type d’enregistrement d’activité.

KnowledgeAgentRetrievalRequest

Objet

Contrat d’entrée pour la demande d’extraction.

Nom	Type	Description
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	Objet de style de message en langage naturel.

KnowledgeAgentRetrievalResponse

Objet

Contrat de sortie pour la réponse d’extraction.

Nom	Type	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	Les enregistrements d’activité permettent de suivre l’avancement et les implications de facturation.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	Les références des données d’extraction utilisées dans la réponse.
response	KnowledgeAgentMessage[]	Objet de style de message en langage naturel.

KnowledgeAgentSearchIndexActivityArguments

Objet

Représente les arguments avec lesquels l’activité d’extraction d’index de recherche a été exécutée.

Nom	Type	Description
filter	string	Chaîne de filtre.
search	string	Chaîne de recherche utilisée pour interroger l’index de recherche.

KnowledgeAgentSearchIndexActivityRecord

Objet

Représente un enregistrement d’activité d’extraction d’index de recherche.

Nom	Type	Description
count	integer (int32)	Le nombre de documents récupérés qui étaient suffisamment pertinents pour passer le seuil de reranker.
elapsedMs	integer (int32)	Temps écoulé en millisecondes pour l’activité d’extraction.
id	integer (int32)	ID de l’enregistrement d’activité.
knowledgeSourceName	string	Source de connaissances pour l’activité d’extraction.
queryTime	string (date-time)	Temps de requête pour cette activité d’extraction.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	Arguments d’index de recherche pour l’activité d’extraction.
type	string: searchIndex	Type d’enregistrement d’activité.

KnowledgeAgentSearchIndexReference

Objet

Représente une référence de document Recherche Azure.

Nom	Type	Description
activitySource	integer (int32)	ID de l’activité source de la référence.
docKey	string	Clé de document de référence.
id	string	ID de la référence.
rerankerScore	number (float)	Le score du reranker pour la référence du document.
sourceData	object
type	string: searchIndex	Type de référence.

KnowledgeAgentSemanticRerankerActivityRecord

Objet

Représente un enregistrement d’activité de ranker sémantique.

Nom	Type	Description
elapsedMs	integer (int32)	Temps écoulé en millisecondes pour l’activité d’extraction.
id	integer (int32)	ID de l’enregistrement d’activité.
inputTokens	integer (int32)	Nombre de jetons d’entrée pour l’activité de classement sémantique.
type	string: semanticReranker	Type d’enregistrement d’activité.

KnowledgeSourceKind

Énumération

Le type de source de connaissance.

Valeur	Description
searchIndex	Source de connaissances qui lit les données d’un index de recherche.
azureBlob	Source de connaissances qui lit et ingère des données de Stockage Blob Azure dans un index de recherche.

SearchIndexKnowledgeSourceParams

Objet

Spécifie les paramètres d’exécution d’une source de connaissances d’index de recherche

Nom	Type	Description
filterAddOn	string	Une condition de filtre appliquée à l’index (par exemple, 'State eq VA').
kind	string: searchIndex	Le type de source de connaissances.
knowledgeSourceName	string	Nom de l’index auquel les paramètres s’appliquent.