Knowledge Retrieval - Retrieve

Serviço:: Search Service

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

O KnowledgeAgent recupera dados relevantes de repositórios de backup.

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

Parâmetros de URI

Nome	Em	Obrigató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 da solicitação

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

Corpo da solicitação

Nome	Obrigatório	Tipo	Description
messages	True	KnowledgeAgentMessage[]	O objeto de estilo de mensagem de linguagem natural.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

Respostas

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

Exemplos

KnowledgeAgentRetrieve

Solicitação de exemplo

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 de exemplo

Código de status:: 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

Nome	Description
ErrorAdditionalInfo	As informações adicionais do erro de gerenciamento de recursos.
ErrorDetail	O detalhe do erro.
ErrorResponse	Resposta de erro
Image
KnowledgeAgentAzureBlobActivityArguments	Representa os argumentos com os quais a atividade de recuperação de blob do Azure foi executada.
KnowledgeAgentAzureBlobActivityRecord	Representa um registro de atividade de recuperação de blob do Azure.
KnowledgeAgentAzureBlobReference	Representa uma referência de documento do Armazenamento de Blobs do Azure.
KnowledgeAgentMessage	O objeto de estilo de mensagem de 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 do 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 de í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 do Azure Search.
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

Objeto

As informações adicionais do erro de gerenciamento de recursos.

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

ErrorDetail

Objeto

O detalhe do erro.

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

ErrorResponse

Objeto

Resposta de erro

Nome	Tipo	Description
error	ErrorDetail	O objeto de erro.

Image

Objeto

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

KnowledgeAgentAzureBlobActivityArguments

Objeto

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

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

KnowledgeAgentAzureBlobActivityRecord

Objeto

Representa um registro de atividade de recuperação de blob do Azure.

Nome	Tipo	Description
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Os argumentos do blob azul para a atividade de recuperação.
count	integer (int32)	A contagem de documentos recuperados que foram suficientemente relevantes para ultrapassar o limite do reclassificador.
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

Objeto

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

Nome	Tipo	Description
activitySource	integer (int32)	A ID da atividade de origem para a referência.
blobUrl	string	A URL do blob para a referência.
id	string	A 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 da referência.

KnowledgeAgentMessage

Objeto

O objeto de estilo de mensagem de linguagem natural.

Nome	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

Objeto

Tipo de mensagem de texto.

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

KnowledgeAgentMessageTextContent

Objeto

Tipo de mensagem de texto.

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

KnowledgeAgentModelAnswerSynthesisActivityRecord

Objeto

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

Nome	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

Objeto

Representa um registro de atividade de planejamento de consulta LLM.

Nome	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 do 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

Objeto

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

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

KnowledgeAgentRetrievalResponse

Objeto

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

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

KnowledgeAgentSearchIndexActivityArguments

Objeto

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

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

KnowledgeAgentSearchIndexActivityRecord

Objeto

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

Nome	Tipo	Description
count	integer (int32)	A contagem de documentos recuperados que foram suficientemente relevantes para ultrapassar o limite do reclassificador.
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

Objeto

Representa uma referência de documento do Azure Search.

Nome	Tipo	Description
activitySource	integer (int32)	A ID da atividade de origem para a referência.
docKey	string	A chave do documento para a referência.
id	string	A 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 da referência.

KnowledgeAgentSemanticRerankerActivityRecord

Objeto

Representa um registro de atividade do classificador semântico.

Nome	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 do classificador semântico.
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 em um Índice de Pesquisa.

SearchIndexKnowledgeSourceParams

Objeto

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

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