Knowledge Agents - Create

Servicio:: Search Service

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

Crea un nuevo agente.

POST {endpoint}/agents?api-version=2025-08-01-preview

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
endpoint	path	True	string	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.

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Description
knowledgeSources	True	KnowledgeSourceReference[]
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Contiene opciones de configuración sobre cómo conectarse a modelos de IA.
name	True	string	El nombre del agente de conocimiento.
@odata.etag		string	La ETag del agente.
description		string	Descripción del agente.
encryptionKey		SearchResourceEncryptionKey	Descripción de una clave de cifrado que se crea en Azure Key Vault. Esta clave se usa para proporcionar un nivel adicional de cifrado en reposo para la definición del agente cuando desea una garantía total de que nadie, ni siquiera Microsoft, puede descifrarlos. Una vez que haya cifrado la definición del agente, siempre permanecerá encriptada. El servicio de búsqueda omitirá los intentos de establecer esta propiedad en null. Puede cambiar esta propiedad según sea necesario si desea rotar su clave de cifrado; La definición de su agente no se verá afectada. El cifrado con claves administradas por el cliente no está disponible para los servicios de búsqueda gratuitos y solo está disponible para los servicios pagos creados a partir del 1 de enero de 2019.
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	Barreras de protección para limitar la cantidad de recursos que se utilizan para una sola solicitud de recuperación de agente.
retrievalInstructions		string	Instrucciones consideradas por el agente de conocimiento al desarrollar el plan de consulta.

Respuestas

Nombre	Tipo	Description
201 Created	KnowledgeAgent	Creó correctamente un agente
Other Status Codes	ErrorResponse	Respuesta de error.

Ejemplos

SearchServiceCreateKnowledgeAgent

Solicitud de ejemplo

HTTP

POST https://previewexampleservice.search.windows.net/agents?api-version=2025-08-01-preview


{
  "name": "agent-preview-test",
  "models": [
    {
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4.1-nano"
      },
      "kind": "azureOpenAI"
    }
  ],
  "knowledgeSources": [
    {
      "name": "ks-preview-test",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "alwaysQuerySource": true,
      "maxSubQueries": 5,
      "rerankerThreshold": 2.1
    }
  ],
  "outputConfiguration": {
    "modality": "extractiveData",
    "answerInstructions": "Provide a concise answer to the question.",
    "attemptFastPath": false,
    "includeActivity": true
  },
  "requestLimits": {
    "maxRuntimeInSeconds": 60,
    "maxOutputSize": 100000
  },
  "retrievalInstructions": "Instructions for retrieval for the agent.",
  "@odata.etag": "0x1234568AE7E58A1",
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "description": "Description of the agent."
}

Respuesta de muestra

status code:: 201

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "agent-preview-test",
  "description": "Description of the agent.",
  "retrievalInstructions": "Instructions for retrieval for the agent.",
  "knowledgeSources": [
    {
      "name": "ks-preview-test",
      "alwaysQuerySource": true,
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "maxSubQueries": 5,
      "rerankerThreshold": 2.1
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4.1-nano"
      }
    }
  ],
  "outputConfiguration": {
    "modality": "extractiveData",
    "answerInstructions": "Provide a concise answer to the question.",
    "attemptFastPath": false,
    "includeActivity": true
  },
  "requestLimits": {
    "maxRuntimeInSeconds": 60,
    "maxOutputSize": 100000
  },
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  }
}

Definiciones

Nombre	Description
AzureActiveDirectoryApplicationCredentials	Credenciales de una aplicación registrada creada para el servicio de búsqueda, usadas para el acceso autenticado a las claves de cifrado almacenadas en Azure Key Vault.
AzureOpenAIEmbeddingSkill	Permite generar una inserción vectorial para una entrada de texto determinada mediante el recurso de Azure OpenAI.
AzureOpenAIModelName	Nombre del modelo de Azure Open AI al que se llamará.
AzureOpenAIParameters	Especifica los parámetros para conectarse al recurso de Azure OpenAI.
ErrorAdditionalInfo	Información adicional sobre el error de administración de recursos.
ErrorDetail	Detalle del error.
ErrorResponse	Respuesta de error
InputFieldMappingEntry	Asignación de campos de entrada para una aptitud.
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	Especifica el recurso de Azure OpenAI que se usa para realizar la planeación de consultas.
KnowledgeAgentModelKind	El modelo de IA que se utilizará para la planificación de consultas.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	La configuración de salida para el agente
KnowledgeAgentRequestLimits	Barreras de protección para limitar la cantidad de recursos que se utilizan para una sola solicitud de recuperación de agente.
KnowledgeSourceReference
OutputFieldMappingEntry	Asignación de campos de salida para una aptitud.
SearchIndexerDataNoneIdentity	Borra la propiedad de identidad de un origen de datos.
SearchIndexerDataUserAssignedIdentity	Especifica la identidad de un origen de datos que se va a utilizar.
SearchResourceEncryptionKey	Una clave de cifrado administrada por el cliente en Azure Key Vault. Las claves que crea y administra se pueden usar para cifrar o descifrar datos en reposo, como índices y mapas de sinónimos.

AzureActiveDirectoryApplicationCredentials

Objeto

Credenciales de una aplicación registrada creada para el servicio de búsqueda, usadas para el acceso autenticado a las claves de cifrado almacenadas en Azure Key Vault.

Nombre	Tipo	Description
applicationId	string	Un identificador de aplicación de AAD al que se concedieron los permisos de acceso necesarios a Azure Key Vault que se usará al cifrar los datos en reposo. El identificador de aplicación no debe confundirse con el identificador de objeto de la aplicación de AAD.
applicationSecret	string	Clave de autenticación de la aplicación de AAD especificada.

AzureOpenAIEmbeddingSkill

Objeto

Permite generar una inserción vectorial para una entrada de texto determinada mediante el recurso de Azure OpenAI.

Nombre	Tipo	Description
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Un fragmento de URI que especifica el tipo de aptitud.
apiKey	string	Clave de API del recurso de Azure OpenAI designado.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	La identidad administrada asignada por el usuario que se usa para las conexiones salientes.
context	string	Representa el nivel en el que tienen lugar las operaciones, como la raíz del documento o el contenido del documento (por ejemplo, /document o /document/content). El valor predeterminado es /document.
deploymentId	string	Identificador de la implementación del modelo de Azure OpenAI en el recurso designado.
description	string	La descripción de la aptitud que describe las entradas, salidas y uso de la aptitud.
dimensions	integer (int32)	Número de dimensiones que deben tener las incrustaciones de salida resultantes. Solo se admite en text-embedding-3 y modelos posteriores.
inputs	InputFieldMappingEntry[]	Las entradas de las aptitudes pueden ser una columna en el conjunto de datos de origen o la salida de una aptitud ascendente.
modelName	AzureOpenAIModelName	Nombre del modelo de incrustación que se implementa en la ruta deploymentId proporcionada.
name	string	El nombre de la aptitud que la identifica de forma única dentro del conjunto de aptitudes. A una habilidad sin nombre definido se le asignará un nombre predeterminado de su índice basado en 1 en la matriz de habilidades, con el prefijo del carácter '#'.
outputs	OutputFieldMappingEntry[]	La salida de una aptitud es un campo de un índice de búsqueda o un valor que otra aptitud puede consumir como entrada.
resourceUri	string (uri)	URI del recurso de Azure OpenAI.

AzureOpenAIModelName

Enumeración

Nombre del modelo de Azure Open AI al que se llamará.

Valor	Description
text-embedding-ada-002
text-embedding-3-large
text-embedding-3-small
gpt-4o
gpt-4o-mini
gpt-4.1
gpt-4.1-mini
gpt-4.1-nano

AzureOpenAIParameters

Objeto

Especifica los parámetros para conectarse al recurso de Azure OpenAI.

Nombre	Tipo	Description
apiKey	string	Clave de API del recurso de Azure OpenAI designado.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	La identidad administrada asignada por el usuario que se usa para las conexiones salientes.
deploymentId	string	Identificador de la implementación del modelo de Azure OpenAI en el recurso designado.
modelName	AzureOpenAIModelName	Nombre del modelo de incrustación que se implementa en la ruta deploymentId proporcionada.
resourceUri	string (uri)	URI del recurso de Azure OpenAI.

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.

InputFieldMappingEntry

Objeto

Asignación de campos de entrada para una aptitud.

Nombre	Tipo	Description
inputs	InputFieldMappingEntry[]	Las entradas recursivas que se usan al crear un tipo complejo.
name	string	Nombre de la entrada.
source	string	El origen de la entrada.
sourceContext	string	El contexto de origen utilizado para seleccionar entradas recursivas.

KnowledgeAgent

Objeto

Nombre	Tipo	Description
@odata.etag	string	La ETag del agente.
description	string	Descripción del agente.
encryptionKey	SearchResourceEncryptionKey	Descripción de una clave de cifrado que se crea en Azure Key Vault. Esta clave se usa para proporcionar un nivel adicional de cifrado en reposo para la definición del agente cuando desea una garantía total de que nadie, ni siquiera Microsoft, puede descifrarlos. Una vez que haya cifrado la definición del agente, siempre permanecerá encriptada. El servicio de búsqueda omitirá los intentos de establecer esta propiedad en null. Puede cambiar esta propiedad según sea necesario si desea rotar su clave de cifrado; La definición de su agente no se verá afectada. El cifrado con claves administradas por el cliente no está disponible para los servicios de búsqueda gratuitos y solo está disponible para los servicios pagos creados a partir del 1 de enero de 2019.
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Contiene opciones de configuración sobre cómo conectarse a modelos de IA.
name	string	El nombre del agente de conocimiento.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Barreras de protección para limitar la cantidad de recursos que se utilizan para una sola solicitud de recuperación de agente.
retrievalInstructions	string	Instrucciones consideradas por el agente de conocimiento al desarrollar el plan de consulta.

KnowledgeAgentAzureOpenAIModel

Objeto

Especifica el recurso de Azure OpenAI que se usa para realizar la planeación de consultas.

Nombre	Tipo	Description
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Contiene los parámetros específicos del punto de conexión del modelo de Azure OpenAI.
kind	string: azureOpenAI	El tipo de modelo de IA.

KnowledgeAgentModelKind

Enumeración

El modelo de IA que se utilizará para la planificación de consultas.

Valor	Description
azureOpenAI	Use modelos de Azure Open AI para la planeación de consultas.

KnowledgeAgentOutputConfiguration

Objeto

Nombre	Tipo	Description
answerInstructions	string	Instrucciones consideradas por el agente de conocimiento al generar respuestas
attemptFastPath	boolean	Indica si el agente debe intentar emitir el mensaje de chat más reciente como una consulta directa a los orígenes de conocimiento, omitiendo las llamadas al modelo.
includeActivity	boolean	Indica que los resultados de la recuperación deben incluir información de la actividad.
modality	KnowledgeAgentOutputConfigurationModality	La configuración de salida para el agente

KnowledgeAgentOutputConfigurationModality

Enumeración

La configuración de salida para el agente

Valor	Description
answerSynthesis	Sintetiza una respuesta para la carga útil de respuesta.
extractiveData	Devolver datos de las fuentes de conocimiento directamente sin alteración generativa.

KnowledgeAgentRequestLimits

Objeto

Barreras de protección para limitar la cantidad de recursos que se utilizan para una sola solicitud de recuperación de agente.

Nombre	Tipo	Description
maxOutputSize	integer (int32)	Limita el tamaño máximo del contenido de la salida.
maxRuntimeInSeconds	integer (int32)	El tiempo máximo de ejecución en segundos.

KnowledgeSourceReference

Objeto

Nombre	Tipo	Description
alwaysQuerySource	boolean	Indica que este origen de conocimiento debe omitir la selección de origen y consultarse siempre en el momento de la recuperación.
includeReferenceSourceData	boolean	Indica si las referencias deben incluir los datos estructurados obtenidos durante la recuperación en su carga útil.
includeReferences	boolean	Indica si se deben incluir referencias para los datos recuperados de este origen.
maxSubQueries	integer (int32)	El número máximo de consultas que se pueden emitir a la vez al recuperar datos de este origen.
name	string	El nombre de la fuente de conocimiento.
rerankerThreshold	number (float)	El umbral de reranker que deben cumplir todos los documentos recuperados para ser incluidos en la respuesta.

OutputFieldMappingEntry

Objeto

Asignación de campos de salida para una aptitud.

Nombre	Tipo	Description
name	string	El nombre de la salida definida por la aptitud.
targetName	string	El nombre de destino de la salida. Es opcional y por defecto nombrar.

SearchIndexerDataNoneIdentity

Objeto

Borra la propiedad de identidad de un origen de datos.

Nombre	Tipo	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Fragmento de URI que especifica el tipo de identidad.

SearchIndexerDataUserAssignedIdentity

Objeto

Especifica la identidad de un origen de datos que se va a utilizar.

Nombre	Tipo	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Fragmento de URI que especifica el tipo de identidad.
userAssignedIdentity	string	Identificador de recurso completo de Azure de una identidad administrada asignada por el usuario, normalmente con el formato "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" que debería haberse asignado al servicio de búsqueda.

SearchResourceEncryptionKey

Objeto

Una clave de cifrado administrada por el cliente en Azure Key Vault. Las claves que crea y administra se pueden usar para cifrar o descifrar datos en reposo, como índices y mapas de sinónimos.

Nombre	Tipo	Description
accessCredentials	AzureActiveDirectoryApplicationCredentials	Credenciales opcionales de Azure Active Directory usadas para acceder a Azure Key Vault. No es necesario si se usa la identidad administrada en su lugar.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Una identidad administrada explícita que se usará para esta clave de cifrado. Si no se especifica y la propiedad de credenciales de acceso es null, se usa la identidad administrada asignada por el sistema. Al actualizar el recurso, si no se especifica la identidad explícita, permanece sin cambios. Si se especifica "none", se borra el valor de esta propiedad.
keyVaultKeyName	string	Nombre de la clave de Azure Key Vault que se usará para cifrar los datos en reposo.
keyVaultKeyVersion	string	La versión de la clave de Azure Key Vault que se usará para cifrar los datos en reposo.
keyVaultUri	string	El URI de Azure Key Vault, también conocido como nombre DNS, que contiene la clave que se usará para cifrar los datos en reposo. Un ejemplo de URI podría ser `https://my-keyvault-name.vault.azure.net`.