Knowledge Retrieval - Retrieve

Servicio:: Search Service

Versión de la API:: 2025-08-01-preview

KnowledgeAgent recupera datos relevantes de los almacenes de respaldo.

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

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
agentName	path	True	string	Nombre del agente.
endpoint	path	True	string (url)	La dirección URL del punto de conexión del servicio de búsqueda.
api-version	query	True	string	Versión de la API del cliente.

Encabezado de la solicitud

Nombre	Requerido	Tipo	Description
x-ms-client-request-id		string (uuid)	El identificador de seguimiento enviado con la solicitud para ayudar con la depuración.
x-ms-query-source-authorization		string	Token que identifica al usuario para el que se ejecuta la consulta. Este token se utiliza para aplicar restricciones de seguridad en los documentos.

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Description
messages	True	KnowledgeAgentMessage[]	El objeto de estilo de mensaje de lenguaje natural.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

Respuestas

Nombre	Tipo	Description
200 OK	KnowledgeAgentRetrievalResponse	La respuesta de recuperación se devuelve correctamente.
Other Status Codes	ErrorResponse	Respuesta de error.

Ejemplos

KnowledgeAgentRetrieve

Solicitud de ejemplo

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

Respuesta de muestra

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

Definiciones

Nombre	Description
ErrorAdditionalInfo	Información adicional sobre el error de administración de recursos.
ErrorDetail	Detalle del error.
ErrorResponse	Respuesta de error
Image
KnowledgeAgentAzureBlobActivityArguments	Representa los argumentos con los que se ejecutó la actividad de recuperación de blobs de Azure.
KnowledgeAgentAzureBlobActivityRecord	Representa un registro de actividad de recuperación de blobs de Azure.
KnowledgeAgentAzureBlobReference	Representa una referencia de documento de Azure Blob Storage.
KnowledgeAgentMessage	El objeto de estilo de mensaje de lenguaje natural.
KnowledgeAgentMessageContentType	El tipo de contenido del mensaje.
KnowledgeAgentMessageImageContent	Tipo de mensaje de texto.
KnowledgeAgentMessageTextContent	Tipo de mensaje de texto.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Representa un registro de actividad de síntesis de respuestas LLM.
KnowledgeAgentModelQueryPlanningActivityRecord	Representa un registro de actividad de planeación de consultas LLM.
KnowledgeAgentRetrievalRequest	El contrato de entrada para la solicitud de recuperación.
KnowledgeAgentRetrievalResponse	El contrato de salida para la respuesta de recuperación.
KnowledgeAgentSearchIndexActivityArguments	Representa los argumentos con los que se ejecutó la actividad de recuperación del índice de búsqueda.
KnowledgeAgentSearchIndexActivityRecord	Representa un registro de actividad de recuperación de índice de búsqueda.
KnowledgeAgentSearchIndexReference	Representa una referencia de documento de Búsqueda de Azure.
KnowledgeAgentSemanticRerankerActivityRecord	Representa un registro de actividad del clasificador semántico.
KnowledgeSourceKind	El tipo de fuente de conocimiento.
SearchIndexKnowledgeSourceParams	Especifica parámetros de tiempo de ejecución para un origen de conocimiento de índice de búsqueda

ErrorAdditionalInfo

Objeto

Información adicional sobre el error de administración de recursos.

Nombre	Tipo	Description
info	object	Información adicional.
type	string	Tipo de información adicional.

ErrorDetail

Objeto

Detalle del error.

Nombre	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	Información adicional del error.
code	string	Código de error.
details	ErrorDetail[]	Los detalles del error.
message	string	El mensaje de error.
target	string	Destino del error.

ErrorResponse

Objeto

Respuesta de error

Nombre	Tipo	Description
error	ErrorDetail	Objeto de error.

Image

Objeto

Nombre	Tipo	Description
url	string (uri)	Dirección URL de la imagen.

KnowledgeAgentAzureBlobActivityArguments

Objeto

Representa los argumentos con los que se ejecutó la actividad de recuperación de blobs de Azure.

Nombre	Tipo	Description
search	string	Cadena de búsqueda que se usa para consultar el contenido del blob.

KnowledgeAgentAzureBlobActivityRecord

Objeto

Representa un registro de actividad de recuperación de blobs de Azure.

Nombre	Tipo	Description
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Los argumentos del blob azur para la actividad de recuperación.
count	integer (int32)	El recuento de documentos recuperados que fueron lo suficientemente relevantes como para pasar el umbral del reranker.
elapsedMs	integer (int32)	El tiempo transcurrido en milisegundos para la actividad de recuperación.
id	integer (int32)	El ID del registro de actividad.
knowledgeSourceName	string	La fuente de conocimiento para la actividad de recuperación.
queryTime	string (date-time)	El tiempo de consulta para esta actividad de recuperación.
type	string: azureBlob	El tipo de registro de actividad.

KnowledgeAgentAzureBlobReference

Objeto

Representa una referencia de documento de Azure Blob Storage.

Nombre	Tipo	Description
activitySource	integer (int32)	El identificador de actividad de origen de la referencia.
blobUrl	string	La dirección URL del blob para la referencia.
id	string	El ID de la referencia.
rerankerScore	number (float)	La puntuación del reranker para la referencia del documento.
sourceData	object
type	string: azureBlob	El tipo de referencia.

KnowledgeAgentMessage

Objeto

El objeto de estilo de mensaje de lenguaje natural.

Nombre	Tipo	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Especifica el tipo de contenido del mensaje.
role	string	El papel de la respuesta de la herramienta.

KnowledgeAgentMessageContentType

Enumeración

El tipo de contenido del mensaje.

Valor	Description
text	Tipo de contenido de mensajes de texto.
image	Tipo de contenido del mensaje de imagen.

KnowledgeAgentMessageImageContent

Objeto

Tipo de mensaje de texto.

Nombre	Tipo	Description
image	Image
type	string: image	El tipo de mensaje

KnowledgeAgentMessageTextContent

Objeto

Tipo de mensaje de texto.

Nombre	Tipo	Description
text	string
type	string: text	El tipo de mensaje

KnowledgeAgentModelAnswerSynthesisActivityRecord

Objeto

Representa un registro de actividad de síntesis de respuestas LLM.

Nombre	Tipo	Description
elapsedMs	integer (int32)	El tiempo transcurrido en milisegundos para la actividad de recuperación.
id	integer (int32)	El ID del registro de actividad.
inputTokens	integer (int32)	El número de tokens de entrada para la actividad de síntesis de respuestas LLM.
outputTokens	integer (int32)	El número de tokens de salida para la actividad de síntesis de respuestas LLM.
type	string: modelAnswerSynthesis	El tipo de registro de actividad.

KnowledgeAgentModelQueryPlanningActivityRecord

Objeto

Representa un registro de actividad de planeación de consultas LLM.

Nombre	Tipo	Description
elapsedMs	integer (int32)	El tiempo transcurrido en milisegundos para la actividad de recuperación.
id	integer (int32)	El ID del registro de actividad.
inputTokens	integer (int32)	Número de tokens de entrada para la actividad de planeación de consultas LLM.
outputTokens	integer (int32)	Número de tokens de salida para la actividad de planeación de consultas LLM.
type	string: modelQueryPlanning	El tipo de registro de actividad.

KnowledgeAgentRetrievalRequest

Objeto

El contrato de entrada para la solicitud de recuperación.

Nombre	Tipo	Description
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	El objeto de estilo de mensaje de lenguaje natural.

KnowledgeAgentRetrievalResponse

Objeto

El contrato de salida para la respuesta de recuperación.

Nombre	Tipo	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	Los registros de actividad para realizar un seguimiento del progreso y las implicaciones de facturación.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	Las referencias de los datos de recuperación utilizados en la respuesta.
response	KnowledgeAgentMessage[]	El objeto de estilo de mensaje de lenguaje natural.

KnowledgeAgentSearchIndexActivityArguments

Objeto

Representa los argumentos con los que se ejecutó la actividad de recuperación del índice de búsqueda.

Nombre	Tipo	Description
filter	string	Cadena de filtro.
search	string	La cadena de búsqueda utilizada para consultar el índice de búsqueda.

KnowledgeAgentSearchIndexActivityRecord

Objeto

Representa un registro de actividad de recuperación de índice de búsqueda.

Nombre	Tipo	Description
count	integer (int32)	El recuento de documentos recuperados que fueron lo suficientemente relevantes como para pasar el umbral del reranker.
elapsedMs	integer (int32)	El tiempo transcurrido en milisegundos para la actividad de recuperación.
id	integer (int32)	El ID del registro de actividad.
knowledgeSourceName	string	La fuente de conocimiento para la actividad de recuperación.
queryTime	string (date-time)	El tiempo de consulta para esta actividad de recuperación.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	Los argumentos del índice de búsqueda para la actividad de recuperación.
type	string: searchIndex	El tipo de registro de actividad.

KnowledgeAgentSearchIndexReference

Objeto

Representa una referencia de documento de Búsqueda de Azure.

Nombre	Tipo	Description
activitySource	integer (int32)	El identificador de actividad de origen de la referencia.
docKey	string	La clave de documento para la referencia.
id	string	El ID de la referencia.
rerankerScore	number (float)	La puntuación del reranker para la referencia del documento.
sourceData	object
type	string: searchIndex	El tipo de referencia.

KnowledgeAgentSemanticRerankerActivityRecord

Objeto

Representa un registro de actividad del clasificador semántico.

Nombre	Tipo	Description
elapsedMs	integer (int32)	El tiempo transcurrido en milisegundos para la actividad de recuperación.
id	integer (int32)	El ID del registro de actividad.
inputTokens	integer (int32)	Número de tokens de entrada para la actividad del clasificador semántico.
type	string: semanticReranker	El tipo de registro de actividad.

KnowledgeSourceKind

Enumeración

El tipo de fuente de conocimiento.

Valor	Description
searchIndex	Un origen de conocimiento que lee datos de un índice de búsqueda.
azureBlob	Un origen de conocimiento que lee e ingiere datos de Azure Blob Storage en un índice de búsqueda.

SearchIndexKnowledgeSourceParams

Objeto

Especifica parámetros de tiempo de ejecución para un origen de conocimiento de índice de búsqueda

Nombre	Tipo	Description
filterAddOn	string	Una condición de filtro aplicada al índice (por ejemplo, 'State eq VA').
kind	string: searchIndex	El tipo de fuente de conocimiento.
knowledgeSourceName	string	Nombre del índice al que se aplican los parámetros.