Knowledge Retrieval - Retrieve

Service:: Search Service

API-versie:: 2025-08-01-preview

KnowledgeAgent haalt relevante gegevens op uit backingstores.

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

URI-parameters

Name	In	Vereist	Type	Description
agentName	path	True	string	De naam van de agent.
endpoint	path	True	string (url)	De eindpunt-URL van de zoekservice.
api-version	query	True	string	Client-API-versie.

Aanvraagkoptekst

Name	Vereist	Type	Description
x-ms-client-request-id		string (uuid)	De tracking-ID die is verzonden met het verzoek om te helpen bij het opsporen.
x-ms-query-source-authorization		string	Token dat de gebruiker identificeert waarvoor de query wordt uitgevoerd. Dit token wordt gebruikt om beveiligingsbeperkingen op documenten af te dwingen.

Aanvraagbody

Name	Vereist	Type	Description
messages	True	KnowledgeAgentMessage[]	Het object in de stijl van berichten in natuurlijke taal.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

Antwoorden

Name	Type	Description
200 OK	KnowledgeAgentRetrievalResponse	Het ophaalantwoord wordt met succes geretourneerd.
Other Status Codes	ErrorResponse	Foutreactie.

Voorbeelden

KnowledgeAgentRetrieve

Voorbeeldaanvraag

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

Voorbeeldrespons

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

Definities

Name	Description
ErrorAdditionalInfo	Aanvullende informatie over de resourcebeheerfout.
ErrorDetail	De foutdetails.
ErrorResponse	Foutreactie
Image
KnowledgeAgentAzureBlobActivityArguments	Vertegenwoordigt de argumenten waarmee de activiteit voor het ophalen van azure-blobs is uitgevoerd.
KnowledgeAgentAzureBlobActivityRecord	Vertegenwoordigt een activiteitsrecord voor het ophalen van Azure-blobs.
KnowledgeAgentAzureBlobReference	Vertegenwoordigt een Azure Blob Storage-documentverwijzing.
KnowledgeAgentMessage	Het object in de stijl van berichten in natuurlijke taal.
KnowledgeAgentMessageContentType	Het type berichtinhoud.
KnowledgeAgentMessageImageContent	Type tekstbericht.
KnowledgeAgentMessageTextContent	Type tekstbericht.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Vertegenwoordigt een activiteitsrecord voor de synthese van LLM-antwoorden.
KnowledgeAgentModelQueryPlanningActivityRecord	Vertegenwoordigt een activiteitsrecord voor LLM-queryplanning.
KnowledgeAgentRetrievalRequest	Het invoercontract voor het opgehaalde verzoek.
KnowledgeAgentRetrievalResponse	Het outputcontract voor het ophaalantwoord.
KnowledgeAgentSearchIndexActivityArguments	Vertegenwoordigt de argumenten waarmee de zoekindexophaalactiviteit is uitgevoerd.
KnowledgeAgentSearchIndexActivityRecord	Vertegenwoordigt een activiteitsrecord voor het ophalen van een zoekindex.
KnowledgeAgentSearchIndexReference	Vertegenwoordigt een Azure Search-documentverwijzing.
KnowledgeAgentSemanticRerankerActivityRecord	Vertegenwoordigt een semantische rangschikkingsactiviteitsrecord.
KnowledgeSourceKind	Het soort kennisbron.
SearchIndexKnowledgeSourceParams	Hiermee geeft u runtimeparameters op voor een kennisbron van een zoekindex

ErrorAdditionalInfo

Object

Aanvullende informatie over de resourcebeheerfout.

Name	Type	Description
info	object	De aanvullende informatie.
type	string	Het extra informatietype.

ErrorDetail

Object

De foutdetails.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	De fout bevat aanvullende informatie.
code	string	De foutcode.
details	ErrorDetail[]	De foutdetails.
message	string	Het foutbericht.
target	string	Het foutdoel.

ErrorResponse

Object

Foutreactie

Name	Type	Description
error	ErrorDetail	Het foutobject.

Image

Object

Name	Type	Description
url	string (uri)	De url van de afbeelding.

KnowledgeAgentAzureBlobActivityArguments

Object

Vertegenwoordigt de argumenten waarmee de activiteit voor het ophalen van azure-blobs is uitgevoerd.

Name	Type	Description
search	string	De zoekreeks die wordt gebruikt om de inhoud van blobs op te vragen.

KnowledgeAgentAzureBlobActivityRecord

Object

Vertegenwoordigt een activiteitsrecord voor het ophalen van Azure-blobs.

Name	Type	Description
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	De azure blob-argumenten voor de ophaalactiviteit.
count	integer (int32)	Het aantal opgehaalde documenten dat voldoende relevant was om de herrangschikkingsdrempel te overschrijden.
elapsedMs	integer (int32)	De verstreken tijd in milliseconden voor de ophaalactiviteit.
id	integer (int32)	De ID van de activiteitsrecord.
knowledgeSourceName	string	De kennisbron voor de ophaalactiviteit.
queryTime	string (date-time)	De querytijd voor deze ophaalactiviteit.
type	string: azureBlob	Het type activiteitsrecord.

KnowledgeAgentAzureBlobReference

Object

Vertegenwoordigt een Azure Blob Storage-documentverwijzing.

Name	Type	Description
activitySource	integer (int32)	De bronactiviteit-id voor de referentie.
blobUrl	string	De blob-URL voor de verwijzing.
id	string	De ID van de referentie.
rerankerScore	number (float)	De herindelingsscore voor de documentreferentie.
sourceData	object
type	string: azureBlob	Het type referentie.

KnowledgeAgentMessage

Object

Het object in de stijl van berichten in natuurlijke taal.

Name	Type	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Hiermee geeft u het type inhoud van het bericht op.
role	string	De rol van de reactie van de tool.

KnowledgeAgentMessageContentType

Opsomming

Het type berichtinhoud.

Waarde	Description
text	Soort van inhoud van sms-berichten.
image	Soort afbeeldingsbericht.

KnowledgeAgentMessageImageContent

Object

Type tekstbericht.

Name	Type	Description
image	Image
type	string: image	Het type bericht

KnowledgeAgentMessageTextContent

Object

Type tekstbericht.

Name	Type	Description
text	string
type	string: text	Het type bericht

KnowledgeAgentModelAnswerSynthesisActivityRecord

Object

Vertegenwoordigt een activiteitsrecord voor de synthese van LLM-antwoorden.

Name	Type	Description
elapsedMs	integer (int32)	De verstreken tijd in milliseconden voor de ophaalactiviteit.
id	integer (int32)	De ID van de activiteitsrecord.
inputTokens	integer (int32)	Het aantal invoertokens voor de LLM-antwoordsyntheseactiviteit.
outputTokens	integer (int32)	Het aantal uitvoertokens voor de LLM-antwoordsyntheseactiviteit.
type	string: modelAnswerSynthesis	Het type activiteitsrecord.

KnowledgeAgentModelQueryPlanningActivityRecord

Object

Vertegenwoordigt een activiteitsrecord voor LLM-queryplanning.

Name	Type	Description
elapsedMs	integer (int32)	De verstreken tijd in milliseconden voor de ophaalactiviteit.
id	integer (int32)	De ID van de activiteitsrecord.
inputTokens	integer (int32)	Het aantal invoertokens voor de LLM-queryplanningsactiviteit.
outputTokens	integer (int32)	Het aantal uitvoertokens voor de LLM-queryplanningsactiviteit.
type	string: modelQueryPlanning	Het type activiteitsrecord.

KnowledgeAgentRetrievalRequest

Object

Het invoercontract voor het opgehaalde verzoek.

Name	Type	Description
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	Het object in de stijl van berichten in natuurlijke taal.

KnowledgeAgentRetrievalResponse

Object

Het outputcontract voor het ophaalantwoord.

Name	Type	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	De activiteitsrecords voor het bijhouden van de voortgang en de gevolgen voor de facturering.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	De verwijzingen naar de ophaalgegevens die in het antwoord worden gebruikt.
response	KnowledgeAgentMessage[]	Het object in de stijl van berichten in natuurlijke taal.

KnowledgeAgentSearchIndexActivityArguments

Object

Vertegenwoordigt de argumenten waarmee de zoekindexophaalactiviteit is uitgevoerd.

Name	Type	Description
filter	string	De filtertekenreeks.
search	string	De zoekreeks die wordt gebruikt om een query uit te voeren op de zoekindex.

KnowledgeAgentSearchIndexActivityRecord

Object

Vertegenwoordigt een activiteitsrecord voor het ophalen van een zoekindex.

Name	Type	Description
count	integer (int32)	Het aantal opgehaalde documenten dat voldoende relevant was om de herrangschikkingsdrempel te overschrijden.
elapsedMs	integer (int32)	De verstreken tijd in milliseconden voor de ophaalactiviteit.
id	integer (int32)	De ID van de activiteitsrecord.
knowledgeSourceName	string	De kennisbron voor de ophaalactiviteit.
queryTime	string (date-time)	De querytijd voor deze ophaalactiviteit.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	De zoekindex argumenten voor de ophaalactiviteit.
type	string: searchIndex	Het type activiteitsrecord.

KnowledgeAgentSearchIndexReference

Object

Vertegenwoordigt een Azure Search-documentverwijzing.

Name	Type	Description
activitySource	integer (int32)	De bronactiviteit-id voor de referentie.
docKey	string	De documentsleutel voor de referentie.
id	string	De ID van de referentie.
rerankerScore	number (float)	De herindelingsscore voor de documentreferentie.
sourceData	object
type	string: searchIndex	Het type referentie.

KnowledgeAgentSemanticRerankerActivityRecord

Object

Vertegenwoordigt een semantische rangschikkingsactiviteitsrecord.

Name	Type	Description
elapsedMs	integer (int32)	De verstreken tijd in milliseconden voor de ophaalactiviteit.
id	integer (int32)	De ID van de activiteitsrecord.
inputTokens	integer (int32)	Het aantal invoertokens voor de semantische rangschikkingsactiviteit.
type	string: semanticReranker	Het type activiteitsrecord.

KnowledgeSourceKind

Opsomming

Het soort kennisbron.

Waarde	Description
searchIndex	Een kennisbron die gegevens uit een zoekindex leest.
azureBlob	Een kennisbron die gegevens van Azure Blob Storage leest en opneemt in een zoekindex.

SearchIndexKnowledgeSourceParams

Object

Hiermee geeft u runtimeparameters op voor een kennisbron van een zoekindex

Name	Type	Description
filterAddOn	string	Een filtervoorwaarde die op de index wordt toegepast (bijvoorbeeld 'Staat eq VA').
kind	string: searchIndex	Het type kennisbron.
knowledgeSourceName	string	De naam van de index waarop de parameters van toepassing zijn.