Knowledge Agents - Create Or Update

Service:: Search Service

Version d'API:: 2025-08-01-preview

Crée un nouvel agent ou met à jour un agent s’il existe déjà.

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

Paramètres URI

Nom	Dans	Obligatoire	Type	Description
agentName	path	True	string	Nom de l’agent à créer ou à mettre à jour.
endpoint	path	True	string	URL du point de terminaison du service de recherche.
api-version	query	True	string	Version de l’API client.

En-tête de la demande

Nom	Obligatoire	Type	Description
x-ms-client-request-id		string (uuid)	ID de suivi envoyé avec la demande pour aider au débogage.
If-Match		string	Définit la condition If-Match. L’opération ne sera effectuée que si l’ETag sur le serveur correspond à cette valeur.
If-None-Match		string	Définit la condition If-None-Match. L’opération ne sera effectuée que si l’ETag sur le serveur ne correspond pas à cette valeur.
Prefer	True	string	Pour les requêtes HTTP PUT, indique au service de renvoyer la ressource créée/mise à jour en cas de réussite.

Corps de la demande

Nom	Obligatoire	Type	Description
knowledgeSources	True	KnowledgeSourceReference[]
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Contient des options de configuration sur la façon de se connecter aux modèles d’IA.
name	True	string	Nom de l’agent de connaissances.
@odata.etag		string	L’ETag de l’agent.
description		string	Description de l’agent.
encryptionKey		SearchResourceEncryptionKey	Description d’une clé de chiffrement que vous créez dans Azure Key Vault. Cette clé est utilisée pour fournir un niveau supplémentaire de chiffrement au repos pour la définition de votre agent lorsque vous voulez avoir l’assurance que personne, pas même Microsoft, ne peut les déchiffrer. Une fois que vous avez chiffré la définition de votre agent, celle-ci reste toujours chiffrée. Le service de recherche ignore les tentatives de définition de cette propriété sur null. Vous pouvez modifier cette propriété si nécessaire si vous souhaitez faire pivoter votre clé de chiffrement ; La définition de votre agent n’est pas affectée. Le chiffrement à l’aide de clés gérées par le client n’est pas disponible pour les services de recherche gratuits et n’est disponible que pour les services payants créés à partir du 1er janvier 2019.
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	Garde-fous pour limiter la quantité de ressources utilisées pour une demande d’extraction d’un seul agent.
retrievalInstructions		string	Instructions prises en compte par l’agent de connaissances lors de l’élaboration du plan de requête.

Réponses

Nom	Type	Description
200 OK	KnowledgeAgent
201 Created	KnowledgeAgent
Other Status Codes	ErrorResponse	Réponse d’erreur.

Exemples

SearchServiceCreateOrUpdateKnowledgeAgent

Exemple de requête

HTTP

PUT https://previewexampleservice.search.windows.net/agents('agent-preview-test')?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-4o-mini"
      },
      "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."
}

Exemple de réponse

Code d’état:: 200

{
  "@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-4o-mini"
      }
    }
  ],
  "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>"
    }
  }
}

Code d’état:: 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-4o-mini"
      }
    }
  ],
  "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>"
    }
  }
}

Définitions

Nom	Description
AzureActiveDirectoryApplicationCredentials	Informations d’identification d’une application inscrite créée pour votre service de recherche, utilisée pour l’accès authentifié aux clés de chiffrement stockées dans Azure Key Vault.
AzureOpenAIEmbeddingSkill	Vous permet de générer un incorporation vectorielle pour une entrée de texte donnée à l’aide de la ressource Azure OpenAI.
AzureOpenAIModelName	Nom du modèle Azure Open AI qui sera appelé.
AzureOpenAIParameters	Spécifie les paramètres de connexion à la ressource Azure OpenAI.
ErrorAdditionalInfo	Informations supplémentaires sur l’erreur de gestion des ressources.
ErrorDetail	Détail de l’erreur.
ErrorResponse	Réponse d’erreur
InputFieldMappingEntry	Mappage de champ de saisie pour une compétence.
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	Spécifie la ressource Azure OpenAI utilisée pour la planification des requêtes.
KnowledgeAgentModelKind	Le modèle d’IA à utiliser pour la planification des requêtes.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	Configuration de sortie de l’agent
KnowledgeAgentRequestLimits	Garde-fous pour limiter la quantité de ressources utilisées pour une demande d’extraction d’un seul agent.
KnowledgeSourceReference
OutputFieldMappingEntry	Mappage de champ de sortie pour une compétence.
SearchIndexerDataNoneIdentity	Efface la propriété identity d’une source de données.
SearchIndexerDataUserAssignedIdentity	Spécifie l’identité d’une source de données à utiliser.
SearchResourceEncryptionKey	Clé de chiffrement gérée par le client dans Azure Key Vault. Les clés que vous créez et gérez peuvent être utilisées pour chiffrer ou déchiffrer des données au repos, telles que des index et des cartes de synonymes.

AzureActiveDirectoryApplicationCredentials

Objet

Informations d’identification d’une application inscrite créée pour votre service de recherche, utilisée pour l’accès authentifié aux clés de chiffrement stockées dans Azure Key Vault.

Nom	Type	Description
applicationId	string	ID d’application AAD qui a reçu les autorisations d’accès requises à Azure Key Vault à utiliser lors du chiffrement de vos données au repos. L’ID d’application ne doit pas être confondu avec l’ID d’objet de votre application AAD.
applicationSecret	string	Clé d’authentification de l’application AAD spécifiée.

AzureOpenAIEmbeddingSkill

Objet

Vous permet de générer un incorporation vectorielle pour une entrée de texte donnée à l’aide de la ressource Azure OpenAI.

Nom	Type	Description
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Fragment d’URI spécifiant le type de compétence.
apiKey	string	Clé API de la ressource Azure OpenAI désignée.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identité managée affectée par l’utilisateur utilisée pour les connexions sortantes.
context	string	Représente le niveau auquel les opérations ont lieu, tel que la racine du document ou le contenu du document (par exemple, /document ou /document/content). La valeur par défaut est /document.
deploymentId	string	ID du déploiement du modèle Azure OpenAI sur la ressource désignée.
description	string	Description de la compétence, qui décrit les entrées, les sorties et l’utilisation de la compétence.
dimensions	integer (int32)	Nombre de dimensions que les incorporations de sortie obtenues doivent avoir. Uniquement pris en charge dans text-embedding-3 et les modèles ultérieurs.
inputs	InputFieldMappingEntry[]	Les entrées des compétences peuvent être une colonne dans l’ensemble de données source ou la sortie d’une compétence en amont.
modelName	AzureOpenAIModelName	Nom du modèle d’incorporation déployé au chemin deploymentId fourni.
name	string	Nom de la compétence qui l’identifie de manière unique dans l’ensemble de compétences. Une compétence sans nom défini se verra attribuer un nom par défaut de son index de base 1 dans le tableau des compétences, préfixé par le caractère « # ».
outputs	OutputFieldMappingEntry[]	La sortie d’une compétence est soit un champ dans un index de recherche, soit une valeur qui peut être consommée en tant qu’entrée par une autre compétence.
resourceUri	string (uri)	URI de la ressource Azure OpenAI.

AzureOpenAIModelName

Énumération

Nom du modèle Azure Open AI qui sera appelé.

Valeur	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

Objet

Spécifie les paramètres de connexion à la ressource Azure OpenAI.

Nom	Type	Description
apiKey	string	Clé API de la ressource Azure OpenAI désignée.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identité managée affectée par l’utilisateur utilisée pour les connexions sortantes.
deploymentId	string	ID du déploiement du modèle Azure OpenAI sur la ressource désignée.
modelName	AzureOpenAIModelName	Nom du modèle d’incorporation déployé au chemin deploymentId fourni.
resourceUri	string (uri)	URI de la ressource Azure OpenAI.

ErrorAdditionalInfo

Objet

Informations supplémentaires sur l’erreur de gestion des ressources.

Nom	Type	Description
info	object	Informations supplémentaires.
type	string	Type d’informations supplémentaire.

ErrorDetail

Objet

Détail de l’erreur.

Nom	Type	Description
additionalInfo	ErrorAdditionalInfo[]	Informations supplémentaires sur l’erreur.
code	string	Code d'erreur.
details	ErrorDetail[]	Détails de l’erreur.
message	string	Message d’erreur.
target	string	Cible d’erreur.

ErrorResponse

Objet

Réponse d’erreur

Nom	Type	Description
error	ErrorDetail	Objet d’erreur.

InputFieldMappingEntry

Objet

Mappage de champ de saisie pour une compétence.

Nom	Type	Description
inputs	InputFieldMappingEntry[]	Entrées récursives utilisées lors de la création d’un type complexe.
name	string	Nom de l’entrée.
source	string	Source de l’entrée.
sourceContext	string	Contexte source utilisé pour la sélection des entrées récursives.

KnowledgeAgent

Objet

Nom	Type	Description
@odata.etag	string	L’ETag de l’agent.
description	string	Description de l’agent.
encryptionKey	SearchResourceEncryptionKey	Description d’une clé de chiffrement que vous créez dans Azure Key Vault. Cette clé est utilisée pour fournir un niveau supplémentaire de chiffrement au repos pour la définition de votre agent lorsque vous voulez avoir l’assurance que personne, pas même Microsoft, ne peut les déchiffrer. Une fois que vous avez chiffré la définition de votre agent, celle-ci reste toujours chiffrée. Le service de recherche ignore les tentatives de définition de cette propriété sur null. Vous pouvez modifier cette propriété si nécessaire si vous souhaitez faire pivoter votre clé de chiffrement ; La définition de votre agent n’est pas affectée. Le chiffrement à l’aide de clés gérées par le client n’est pas disponible pour les services de recherche gratuits et n’est disponible que pour les services payants créés à partir du 1er janvier 2019.
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Contient des options de configuration sur la façon de se connecter aux modèles d’IA.
name	string	Nom de l’agent de connaissances.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Garde-fous pour limiter la quantité de ressources utilisées pour une demande d’extraction d’un seul agent.
retrievalInstructions	string	Instructions prises en compte par l’agent de connaissances lors de l’élaboration du plan de requête.

KnowledgeAgentAzureOpenAIModel

Objet

Spécifie la ressource Azure OpenAI utilisée pour la planification des requêtes.

Nom	Type	Description
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Contient les paramètres spécifiques au point de terminaison du modèle Azure OpenAI.
kind	string: azureOpenAI	Le type de modèle d’IA.

KnowledgeAgentModelKind

Énumération

Le modèle d’IA à utiliser pour la planification des requêtes.

Valeur	Description
azureOpenAI	Utilisez les modèles Azure Open AI pour la planification des requêtes.

KnowledgeAgentOutputConfiguration

Objet

Nom	Type	Description
answerInstructions	string	Instructions prises en compte par l’agent de connaissances lors de la génération des réponses
attemptFastPath	boolean	Indique si l’agent doit tenter d’émettre le message de chat le plus récent en tant que requête directe aux sources de connaissances, en contournant les appels de modèle.
includeActivity	boolean	Indique que les résultats de la récupération doivent inclure des informations sur l’activité.
modality	KnowledgeAgentOutputConfigurationModality	Configuration de sortie de l’agent

KnowledgeAgentOutputConfigurationModality

Énumération

Configuration de sortie de l’agent

Valeur	Description
answerSynthesis	Synthétisez une réponse pour la charge utile de réponse.
extractiveData	Retournez des données à partir des sources de connaissances directement sans modification générative.

KnowledgeAgentRequestLimits

Objet

Garde-fous pour limiter la quantité de ressources utilisées pour une demande d’extraction d’un seul agent.

Nom	Type	Description
maxOutputSize	integer (int32)	Limite la taille maximale du contenu dans la sortie.
maxRuntimeInSeconds	integer (int32)	Durée d’exécution maximale en secondes.

KnowledgeSourceReference

Objet

Nom	Type	Description
alwaysQuerySource	boolean	Indique que cette source de connaissances doit contourner la sélection de la source et être toujours interrogée au moment de la récupération.
includeReferenceSourceData	boolean	Indique si les références doivent inclure les données structurées obtenues lors de l’extraction dans leur charge utile.
includeReferences	boolean	Indique si des références doivent être incluses pour les données extraites de cette source.
maxSubQueries	integer (int32)	Nombre maximal de requêtes pouvant être émises à la fois lors de l’extraction de données à partir de cette source.
name	string	Nom de la source de connaissances.
rerankerThreshold	number (float)	Le seuil de reclassement que tous les documents récupérés doivent atteindre pour être inclus dans la réponse.

OutputFieldMappingEntry

Objet

Mappage de champ de sortie pour une compétence.

Nom	Type	Description
name	string	Nom de la sortie défini par la compétence.
targetName	string	Nom cible de la sortie. Il est facultatif et nomme par défaut.

SearchIndexerDataNoneIdentity

Objet

Efface la propriété identity d’une source de données.

Nom	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Fragment d’URI spécifiant le type d’identité.

SearchIndexerDataUserAssignedIdentity

Objet

Spécifie l’identité d’une source de données à utiliser.

Nom	Type	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Fragment d’URI spécifiant le type d’identité.
userAssignedIdentity	string	ID de ressource Azure complet d’un utilisateur affecté à une identité managée, généralement sous la forme « /subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId » qui aurait dû être attribué au service de recherche.

SearchResourceEncryptionKey

Objet

Clé de chiffrement gérée par le client dans Azure Key Vault. Les clés que vous créez et gérez peuvent être utilisées pour chiffrer ou déchiffrer des données au repos, telles que des index et des cartes de synonymes.

Nom	Type	Description
accessCredentials	AzureActiveDirectoryApplicationCredentials	Informations d’identification Azure Active Directory facultatives utilisées pour accéder à votre coffre de clés Azure. Non requis si vous utilisez l’identité managée à la place.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identité managée explicite à utiliser pour cette clé de chiffrement. S’il n’est pas spécifié et que la propriété d’informations d’identification d’accès est nulle, l’identité managée affectée par le système est utilisée. Lors de la mise à jour de la ressource, si l’identité explicite n’est pas spécifiée, elle reste inchangée. Si « none » est spécifié, la valeur de cette propriété est effacée.
keyVaultKeyName	string	Nom de votre clé Azure Key Vault à utiliser pour chiffrer vos données au repos.
keyVaultKeyVersion	string	Version de votre clé Azure Key Vault à utiliser pour chiffrer vos données au repos.
keyVaultUri	string	URI de votre Azure Key Vault, également appelé nom DNS, qui contient la clé à utiliser pour chiffrer vos données au repos. Un exemple d’URI pourrait être `https://my-keyvault-name.vault.azure.net`.