Knowledge Retrieval - Retrieve

Serviço:: Search Service

Versão da API:: 2025-08-01-preview

O KnowledgeAgent recupera dados relevantes de armazenamentos de backup.

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

Parâmetros do URI

Name	Em	Necessário	Tipo	Description
agentName	path	True	string	O nome do agente.
endpoint	path	True	string (url)	A URL do ponto de extremidade do serviço de pesquisa.
api-version	query	True	string	Versão da API do cliente.

Cabeçalho do Pedido

Name	Necessário	Tipo	Description
x-ms-client-request-id		string (uuid)	O ID de rastreamento enviado com a solicitação para ajudar com a depuração.
x-ms-query-source-authorization		string	Token que identifica o usuário para o qual a consulta está sendo executada. Este token é usado para impor restrições de segurança em documentos.

Corpo do Pedido

Name	Necessário	Tipo	Description
messages	True	KnowledgeAgentMessage[]	O objeto de estilo de mensagem em linguagem natural.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

Respostas

Name	Tipo	Description
200 OK	KnowledgeAgentRetrievalResponse	A resposta de recuperação é retornada com êxito.
Other Status Codes	ErrorResponse	Resposta de erro.

Exemplos

KnowledgeAgentRetrieve

Pedido de amostra

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

Resposta da amostra

Código de estado:: 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"
    }
  ]
}

Definições

Name	Description
ErrorAdditionalInfo	O erro de gerenciamento de recursos informações adicionais.
ErrorDetail	O detalhe do erro.
ErrorResponse	Resposta de erro
Image
KnowledgeAgentAzureBlobActivityArguments	Representa os argumentos com os quais a atividade de recuperação de blob azure foi executada.
KnowledgeAgentAzureBlobActivityRecord	Representa um registro de atividade de recuperação de blob azure.
KnowledgeAgentAzureBlobReference	Representa uma referência de documento do Armazenamento de Blobs do Azure.
KnowledgeAgentMessage	O objeto de estilo de mensagem em linguagem natural.
KnowledgeAgentMessageContentType	O tipo de conteúdo da mensagem.
KnowledgeAgentMessageImageContent	Tipo de mensagem de texto.
KnowledgeAgentMessageTextContent	Tipo de mensagem de texto.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Representa um registro de atividade de síntese de resposta LLM.
KnowledgeAgentModelQueryPlanningActivityRecord	Representa um registro de atividade de planejamento de consulta LLM.
KnowledgeAgentRetrievalRequest	O contrato de entrada para a solicitação de recuperação.
KnowledgeAgentRetrievalResponse	O contrato de saída para a resposta de recuperação.
KnowledgeAgentSearchIndexActivityArguments	Representa os argumentos com os quais a atividade de recuperação do índice de pesquisa foi executada.
KnowledgeAgentSearchIndexActivityRecord	Representa um registro de atividade de recuperação de índice de pesquisa.
KnowledgeAgentSearchIndexReference	Representa uma referência de documento da Pesquisa do Azure.
KnowledgeAgentSemanticRerankerActivityRecord	Representa um registro de atividade do classificador semântico.
KnowledgeSourceKind	O tipo de fonte de conhecimento.
SearchIndexKnowledgeSourceParams	Especifica parâmetros de tempo de execução para uma fonte de conhecimento de índice de pesquisa

ErrorAdditionalInfo

Object

O erro de gerenciamento de recursos informações adicionais.

Name	Tipo	Description
info	object	As informações adicionais.
type	string	O tipo de informação adicional.

ErrorDetail

Object

O detalhe do erro.

Name	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	O erro informações adicionais.
code	string	O código de erro.
details	ErrorDetail[]	Os detalhes do erro.
message	string	A mensagem de erro.
target	string	O destino do erro.

ErrorResponse

Object

Resposta de erro

Name	Tipo	Description
error	ErrorDetail	O objeto de erro.

Image

Object

Name	Tipo	Description
url	string (uri)	O url da imagem.

KnowledgeAgentAzureBlobActivityArguments

Object

Representa os argumentos com os quais a atividade de recuperação de blob azure foi executada.

Name	Tipo	Description
search	string	A cadeia de caracteres de pesquisa usada para consultar o conteúdo do blob.

KnowledgeAgentAzureBlobActivityRecord

Object

Representa um registro de atividade de recuperação de blob azure.

Name	Tipo	Description
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Os argumentos azure blob para a atividade de recuperação.
count	integer (int32)	A contagem de documentos recuperados que foram suficientemente relevantes para ultrapassar o limiar de reclassificação.
elapsedMs	integer (int32)	O tempo decorrido em milissegundos para a atividade de recuperação.
id	integer (int32)	A ID do registro de atividade.
knowledgeSourceName	string	A fonte de conhecimento para a atividade de recuperação.
queryTime	string (date-time)	O tempo de consulta para essa atividade de recuperação.
type	string: azureBlob	O tipo de registro de atividade.

KnowledgeAgentAzureBlobReference

Object

Representa uma referência de documento do Armazenamento de Blobs do Azure.

Name	Tipo	Description
activitySource	integer (int32)	O ID da atividade de origem para a referência.
blobUrl	string	O URL de blob para a referência.
id	string	O ID da referência.
rerankerScore	number (float)	A pontuação do reclassificador para a referência do documento.
sourceData	object
type	string: azureBlob	O tipo de referência.

KnowledgeAgentMessage

Object

O objeto de estilo de mensagem em linguagem natural.

Name	Tipo	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Especifica o tipo de conteúdo da mensagem.
role	string	O papel da resposta da ferramenta.

KnowledgeAgentMessageContentType

Enumeração

O tipo de conteúdo da mensagem.

Valor	Description
text	Tipo de conteúdo de mensagem de texto.
image	Tipo de conteúdo da mensagem de imagem.

KnowledgeAgentMessageImageContent

Object

Tipo de mensagem de texto.

Name	Tipo	Description
image	Image
type	string: image	O tipo da mensagem

KnowledgeAgentMessageTextContent

Object

Tipo de mensagem de texto.

Name	Tipo	Description
text	string
type	string: text	O tipo da mensagem

KnowledgeAgentModelAnswerSynthesisActivityRecord

Object

Representa um registro de atividade de síntese de resposta LLM.

Name	Tipo	Description
elapsedMs	integer (int32)	O tempo decorrido em milissegundos para a atividade de recuperação.
id	integer (int32)	A ID do registro de atividade.
inputTokens	integer (int32)	O número de tokens de entrada para a atividade de síntese de resposta LLM.
outputTokens	integer (int32)	O número de tokens de saída para a atividade de síntese de resposta LLM.
type	string: modelAnswerSynthesis	O tipo de registro de atividade.

KnowledgeAgentModelQueryPlanningActivityRecord

Object

Representa um registro de atividade de planejamento de consulta LLM.

Name	Tipo	Description
elapsedMs	integer (int32)	O tempo decorrido em milissegundos para a atividade de recuperação.
id	integer (int32)	A ID do registro de atividade.
inputTokens	integer (int32)	O número de tokens de entrada para a atividade de planejamento de consulta LLM.
outputTokens	integer (int32)	O número de tokens de saída para a atividade de planejamento de consulta LLM.
type	string: modelQueryPlanning	O tipo de registro de atividade.

KnowledgeAgentRetrievalRequest

Object

O contrato de entrada para a solicitação de recuperação.

Name	Tipo	Description
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	O objeto de estilo de mensagem em linguagem natural.

KnowledgeAgentRetrievalResponse

Object

O contrato de saída para a resposta de recuperação.

Name	Tipo	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	Os registros de atividade para acompanhar o progresso e as implicações de faturamento.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	As referências para os dados de recuperação usados na resposta.
response	KnowledgeAgentMessage[]	O objeto de estilo de mensagem em linguagem natural.

KnowledgeAgentSearchIndexActivityArguments

Object

Representa os argumentos com os quais a atividade de recuperação do índice de pesquisa foi executada.

Name	Tipo	Description
filter	string	A cadeia de caracteres do filtro.
search	string	A cadeia de caracteres de pesquisa usada para consultar o índice de pesquisa.

KnowledgeAgentSearchIndexActivityRecord

Object

Representa um registro de atividade de recuperação de índice de pesquisa.

Name	Tipo	Description
count	integer (int32)	A contagem de documentos recuperados que foram suficientemente relevantes para ultrapassar o limiar de reclassificação.
elapsedMs	integer (int32)	O tempo decorrido em milissegundos para a atividade de recuperação.
id	integer (int32)	A ID do registro de atividade.
knowledgeSourceName	string	A fonte de conhecimento para a atividade de recuperação.
queryTime	string (date-time)	O tempo de consulta para essa atividade de recuperação.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	Os argumentos do índice de pesquisa para a atividade de recuperação.
type	string: searchIndex	O tipo de registro de atividade.

KnowledgeAgentSearchIndexReference

Object

Representa uma referência de documento da Pesquisa do Azure.

Name	Tipo	Description
activitySource	integer (int32)	O ID da atividade de origem para a referência.
docKey	string	A chave do documento para a referência.
id	string	O ID da referência.
rerankerScore	number (float)	A pontuação do reclassificador para a referência do documento.
sourceData	object
type	string: searchIndex	O tipo de referência.

KnowledgeAgentSemanticRerankerActivityRecord

Object

Representa um registro de atividade do classificador semântico.

Name	Tipo	Description
elapsedMs	integer (int32)	O tempo decorrido em milissegundos para a atividade de recuperação.
id	integer (int32)	A ID do registro de atividade.
inputTokens	integer (int32)	O número de tokens de entrada para a atividade de classificação semântica.
type	string: semanticReranker	O tipo de registro de atividade.

KnowledgeSourceKind

Enumeração

O tipo de fonte de conhecimento.

Valor	Description
searchIndex	Uma fonte de conhecimento que lê dados de um índice de pesquisa.
azureBlob	Uma fonte de conhecimento que lê e ingere dados do Armazenamento de Blobs do Azure para um Índice de Pesquisa.

SearchIndexKnowledgeSourceParams

Object

Especifica parâmetros de tempo de execução para uma fonte de conhecimento de índice de pesquisa

Name	Tipo	Description
filterAddOn	string	Uma condição de filtro aplicada ao índice (por exemplo, «State eq VA»).
kind	string: searchIndex	O tipo de fonte de conhecimento.
knowledgeSourceName	string	O nome do índice ao qual os parâmetros se aplicam.