Knowledge Agents - Create Or Update

Dienst:: Search Service

API-Version:: 2025-05-01-preview

Erstellt einen neuen Agent oder aktualisiert einen Agent, falls er bereits vorhanden ist.

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

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
agentName	path	True	string	Der Name des Agents, der erstellt oder aktualisiert werden soll.
endpoint	path	True	string	Die Endpunkt-URL des Suchdiensts.
api-version	query	True	string	Client-API-Version.

Anforderungsheader

Name	Erforderlich	Typ	Beschreibung
x-ms-client-request-id		string (uuid)	Die Tracking-ID, die mit der Anforderung gesendet wurde, um beim Debuggen zu helfen.
If-Match		string	Definiert die If-Match Bedingung. Der Vorgang wird nur ausgeführt, wenn das ETag auf dem Server mit diesem Wert übereinstimmt.
If-None-Match		string	Definiert die If-None-Match-Bedingung. Der Vorgang wird nur ausgeführt, wenn das ETag auf dem Server nicht mit diesem Wert übereinstimmt.
Prefer	True	string	Für HTTP PUT-Anforderungen weist der Dienst an, die erstellte/aktualisierte Ressource bei Erfolg zurückzugeben.

Anforderungstext

Name	Erforderlich	Typ	Beschreibung
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Enthält Konfigurationsoptionen zum Herstellen einer Verbindung mit KI-Modellen.
name	True	string	Der Name des Wissensagenten.
targetIndexes	True	KnowledgeAgentTargetIndex[]
@odata.etag		string	Das ETag des Agenten.
description		string	Die Beschreibung des Agenten.
encryptionKey		SearchResourceEncryptionKey	Eine Beschreibung eines Verschlüsselungsschlüssels, den Sie in Azure Key Vault erstellen. Dieser Schlüssel wird verwendet, um eine zusätzliche Ebene der Verschlüsselung ruhender Daten für Ihre Agent-Definition bereitzustellen, wenn Sie die vollständige Gewissheit haben möchten, dass niemand, nicht einmal Microsoft, sie entschlüsseln kann. Nachdem Sie Ihre Agentendefinition verschlüsselt haben, bleibt sie immer verschlüsselt. Der Suchdienst ignoriert Versuche, diese Eigenschaft auf NULL festzulegen. Sie können diese Eigenschaft nach Bedarf ändern, wenn Sie Ihren Verschlüsselungsschlüssel rotieren möchten. Ihre Agentendefinition ist davon nicht betroffen. Verschlüsselung mit vom Kunden verwalteten Schlüsseln steht nicht für kostenlose Suchdienste zur Verfügung und ist nur für kostenpflichtige Dienste verfügbar, die am oder nach dem 1. Januar 2019 erstellt wurden.
requestLimits		KnowledgeAgentRequestLimits	Leitplanken, um zu begrenzen, wie viel Ressourcen für eine einzelne Agentenabrufanforderung verwendet werden.

Antworten

Name	Typ	Beschreibung
200 OK	KnowledgeAgent
201 Created	KnowledgeAgent
Other Status Codes	ErrorResponse	Fehlerantwort.

Beispiele

SearchServiceCreateOrUpdateKnowledgeAgent

Beispielanforderung

HTTP

PUT https://previewexampleservice.search.windows.net/agents('agent-preview-test')?api-version=2025-05-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"
    }
  ],
  "targetIndexes": [
    {
      "indexName": "preview-test",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ],
  "requestLimits": {
    "maxRuntimeInSeconds": 60,
    "maxOutputSize": 100000
  },
  "@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."
}

Beispiel für eine Antwort

Statuscode:: 200

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "agent-preview-test",
  "description": "Description of the agent.",
  "targetIndexes": [
    {
      "indexName": "preview-test",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4o-mini"
      }
    }
  ],
  "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>"
    }
  }
}

Statuscode:: 201

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "agent-preview-test",
  "description": "Description of the agent.",
  "targetIndexes": [
    {
      "indexName": "preview-test",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4o-mini"
      }
    }
  ],
  "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>"
    }
  }
}

Definitionen

Name	Beschreibung
AzureActiveDirectoryApplicationCredentials	Anmeldeinformationen einer registrierten Anwendung, die für Ihren Suchdienst erstellt wurde und für authentifizierten Zugriff auf die im Azure Key Vault gespeicherten Verschlüsselungsschlüssel verwendet wird.
AzureOpenAIEmbeddingSkill	Ermöglicht es Ihnen, einen Vektoreinbettung für eine bestimmte Texteingabe mithilfe der Azure OpenAI-Ressource zu generieren.
AzureOpenAIModelName	Der Name des Azure Open AI-Modells, der aufgerufen wird.
AzureOpenAIParameters	Gibt die Parameter für die Verbindung mit der Azure OpenAI-Ressource an.
ErrorAdditionalInfo	Der Ressourcenverwaltungsfehler zusätzliche Informationen.
ErrorDetail	Das Fehlerdetails.
ErrorResponse	Fehlerantwort
InputFieldMappingEntry	Eingabefeldzuordnung für eine Fähigkeit.
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	Gibt die Azure OpenAI-Ressource an, die für die Abfrageplanung verwendet wird.
KnowledgeAgentModelKind	Das KI-Modell, das für die Abfrageplanung verwendet werden soll.
KnowledgeAgentRequestLimits	Leitplanken, um zu begrenzen, wie viel Ressourcen für eine einzelne Agentenabrufanforderung verwendet werden.
KnowledgeAgentTargetIndex
OutputFieldMappingEntry	Ausgabefeldzuordnung für eine Fähigkeit.
SearchIndexerDataNoneIdentity	Löscht die Identitätseigenschaft einer Datenquelle.
SearchIndexerDataUserAssignedIdentity	Gibt die Identität für eine zu verwendende Datenquelle an.
SearchResourceEncryptionKey	Ein vom Kunden verwalteter Verschlüsselungsschlüssel im Azure Key Vault. Schlüssel, die Sie erstellen und verwalten, können zum Verschlüsseln oder Entschlüsseln ruhender Daten verwendet werden, z. B. Indizes und Synonymzuordnungen.

AzureActiveDirectoryApplicationCredentials

Objekt

Anmeldeinformationen einer registrierten Anwendung, die für Ihren Suchdienst erstellt wurde und für authentifizierten Zugriff auf die im Azure Key Vault gespeicherten Verschlüsselungsschlüssel verwendet wird.

Name	Typ	Beschreibung
applicationId	string	Eine AAD-Anwendungs-ID, die die erforderlichen Zugriffsberechtigungen für den Azure Key Vault erteilt hat, die beim Verschlüsseln Ihrer ruhenden Daten verwendet werden sollen. Die Anwendungs-ID sollte nicht mit der Objekt-ID für Ihre AAD-Anwendung verwechselt werden.
applicationSecret	string	Der Authentifizierungsschlüssel der angegebenen AAD-Anwendung.

AzureOpenAIEmbeddingSkill

Objekt

Ermöglicht es Ihnen, einen Vektoreinbettung für eine bestimmte Texteingabe mithilfe der Azure OpenAI-Ressource zu generieren.

Name	Typ	Beschreibung
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Ein URI-Fragment, das die Art der Fähigkeit angibt.
apiKey	string	API-Schlüssel der angegebenen Azure OpenAI-Ressource.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Die vom Benutzer zugewiesene verwaltete Identität, die für ausgehende Verbindungen verwendet wird.
context	string	Stellt die Ebene dar, auf der Vorgänge ausgeführt werden, z. B. der Dokumentstamm- oder Dokumentinhalt (z. B. /document oder /document/content). Der Standardwert ist /document.
deploymentId	string	ID der Azure OpenAI-Modellbereitstellung für die angegebene Ressource.
description	string	Die Beschreibung der Fähigkeiten, die die Eingaben, Ausgaben und die Nutzung der Fähigkeiten beschreibt.
dimensions	integer (int32)	Die Anzahl der Dimensionen, die die resultierenden Ausgabeeinbettungen aufweisen sollen. Wird nur in Text-Einbettungs-3- und höher-Modellen unterstützt.
inputs	InputFieldMappingEntry[]	Eingaben der Fähigkeiten können eine Spalte im Quelldatensatz oder die Ausgabe einer upstream-Fähigkeit sein.
modelName	AzureOpenAIModelName	Der Name des Einbettungsmodells, das im bereitgestellten deploymentId-Pfad bereitgestellt wird.
name	string	Der Name der Fähigkeit, die sie innerhalb des Skillsets eindeutig identifiziert. Eine Fähigkeit ohne definierten Namen erhält einen Standardnamen des 1-basierten Indexes im Kompetenzarray, dem das Zeichen "#" vorangestellt ist.
outputs	OutputFieldMappingEntry[]	Die Ausgabe einer Fähigkeit ist entweder ein Feld in einem Suchindex oder ein Wert, der als Eingabe durch eine andere Fähigkeit genutzt werden kann.
resourceUri	string (uri)	Der Ressourcen-URI der Azure OpenAI-Ressource.

AzureOpenAIModelName

Enumeration

Der Name des Azure Open AI-Modells, der aufgerufen wird.

Wert	Beschreibung
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

Objekt

Gibt die Parameter für die Verbindung mit der Azure OpenAI-Ressource an.

Name	Typ	Beschreibung
apiKey	string	API-Schlüssel der angegebenen Azure OpenAI-Ressource.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Die vom Benutzer zugewiesene verwaltete Identität, die für ausgehende Verbindungen verwendet wird.
deploymentId	string	ID der Azure OpenAI-Modellbereitstellung für die angegebene Ressource.
modelName	AzureOpenAIModelName	Der Name des Einbettungsmodells, das im bereitgestellten deploymentId-Pfad bereitgestellt wird.
resourceUri	string (uri)	Der Ressourcen-URI der Azure OpenAI-Ressource.

ErrorAdditionalInfo

Objekt

Der Ressourcenverwaltungsfehler zusätzliche Informationen.

Name	Typ	Beschreibung
info	object	Die zusätzlichen Informationen.
type	string	Der zusätzliche Informationstyp.

ErrorDetail

Objekt

Das Fehlerdetails.

Name	Typ	Beschreibung
additionalInfo	ErrorAdditionalInfo[]	Die zusätzlichen Informationen des Fehlers.
code	string	Der Fehlercode.
details	ErrorDetail[]	Die Fehlerdetails.
message	string	Die Fehlermeldung.
target	string	Das Fehlerziel.

ErrorResponse

Objekt

Fehlerantwort

Name	Typ	Beschreibung
error	ErrorDetail	Das Fehlerobjekt.

InputFieldMappingEntry

Objekt

Eingabefeldzuordnung für eine Fähigkeit.

Name	Typ	Beschreibung
inputs	InputFieldMappingEntry[]	Die rekursiven Eingaben, die beim Erstellen eines komplexen Typs verwendet werden.
name	string	Der Name der Eingabe.
source	string	Die Quelle der Eingabe.
sourceContext	string	Der Quellkontext, der zum Auswählen rekursiver Eingaben verwendet wird.

KnowledgeAgent

Objekt

Name	Typ	Beschreibung
@odata.etag	string	Das ETag des Agenten.
description	string	Die Beschreibung des Agenten.
encryptionKey	SearchResourceEncryptionKey	Eine Beschreibung eines Verschlüsselungsschlüssels, den Sie in Azure Key Vault erstellen. Dieser Schlüssel wird verwendet, um eine zusätzliche Ebene der Verschlüsselung ruhender Daten für Ihre Agent-Definition bereitzustellen, wenn Sie die vollständige Gewissheit haben möchten, dass niemand, nicht einmal Microsoft, sie entschlüsseln kann. Nachdem Sie Ihre Agentendefinition verschlüsselt haben, bleibt sie immer verschlüsselt. Der Suchdienst ignoriert Versuche, diese Eigenschaft auf NULL festzulegen. Sie können diese Eigenschaft nach Bedarf ändern, wenn Sie Ihren Verschlüsselungsschlüssel rotieren möchten. Ihre Agentendefinition ist davon nicht betroffen. Verschlüsselung mit vom Kunden verwalteten Schlüsseln steht nicht für kostenlose Suchdienste zur Verfügung und ist nur für kostenpflichtige Dienste verfügbar, die am oder nach dem 1. Januar 2019 erstellt wurden.
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Enthält Konfigurationsoptionen zum Herstellen einer Verbindung mit KI-Modellen.
name	string	Der Name des Wissensagenten.
requestLimits	KnowledgeAgentRequestLimits	Leitplanken, um zu begrenzen, wie viel Ressourcen für eine einzelne Agentenabrufanforderung verwendet werden.
targetIndexes	KnowledgeAgentTargetIndex[]

KnowledgeAgentAzureOpenAIModel

Objekt

Gibt die Azure OpenAI-Ressource an, die für die Abfrageplanung verwendet wird.

Name	Typ	Beschreibung
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Enthält die Parameter, die für den Azure OpenAI-Modellendpunkt spezifisch sind.
kind	string: azureOpenAI	Die Art des KI-Modells.

KnowledgeAgentModelKind

Enumeration

Das KI-Modell, das für die Abfrageplanung verwendet werden soll.

Wert	Beschreibung
azureOpenAI	Verwenden Sie Azure Open AI-Modelle für die Abfrageplanung.

KnowledgeAgentRequestLimits

Objekt

Leitplanken, um zu begrenzen, wie viel Ressourcen für eine einzelne Agentenabrufanforderung verwendet werden.

Name	Typ	Beschreibung
maxOutputSize	integer (int32)	Begrenzt die maximale Größe des Inhalts in der Ausgabe.
maxRuntimeInSeconds	integer (int32)	Die maximale Laufzeit in Sekunden.

KnowledgeAgentTargetIndex

Objekt

Name	Typ	Beschreibung
defaultIncludeReferenceSourceData	boolean	Gibt an, ob Referenzquelldaten eingeschlossen werden sollen.
defaultMaxDocsForReranker	integer (int32)	Begrenzt die Anzahl der Dokumente, die für die Rangfolge berücksichtigt werden.
defaultRerankerThreshold	number (float) minimum: 0 maximum: 4	Ein Schwellenwert für die Neueinstufung von Ergebnissen (Bereich: 0-4).
indexName	string	Der Name des Zielindexes.

OutputFieldMappingEntry

Objekt

Ausgabefeldzuordnung für eine Fähigkeit.

Name	Typ	Beschreibung
name	string	Der Name der Ausgabe, die durch die Fähigkeit definiert wird.
targetName	string	Der Zielname der Ausgabe. Sie ist optional und standardmäßig name.

SearchIndexerDataNoneIdentity

Objekt

Löscht die Identitätseigenschaft einer Datenquelle.

Name	Typ	Beschreibung
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Ein URI-Fragment, das den Identitätstyp angibt.

SearchIndexerDataUserAssignedIdentity

Objekt

Gibt die Identität für eine zu verwendende Datenquelle an.

Name	Typ	Beschreibung
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Ein URI-Fragment, das den Identitätstyp angibt.
userAssignedIdentity	string	Die vollqualifizierte Azure-Ressourcen-ID einer vom Benutzer zugewiesenen verwalteten Identität in der Regel im Format "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId", die dem Suchdienst zugewiesen werden sollen.

SearchResourceEncryptionKey

Objekt

Ein vom Kunden verwalteter Verschlüsselungsschlüssel im Azure Key Vault. Schlüssel, die Sie erstellen und verwalten, können zum Verschlüsseln oder Entschlüsseln ruhender Daten verwendet werden, z. B. Indizes und Synonymzuordnungen.

Name	Typ	Beschreibung
accessCredentials	AzureActiveDirectoryApplicationCredentials	Optionale Azure Active Directory-Anmeldeinformationen, die für den Zugriff auf Ihren Azure Key Vault verwendet werden. Ist nicht erforderlich, wenn stattdessen verwaltete Identität verwendet wird.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Eine explizite verwaltete Identität, die für diesen Verschlüsselungsschlüssel verwendet werden soll. Wenn diese Eigenschaft nicht angegeben ist und die Eigenschaft für Zugriffsanmeldeinformationen null ist, wird die vom System zugewiesene verwaltete Identität verwendet. Wenn die explizite Identität nicht angegeben ist, bleibt die Aktualisierung der Ressource unverändert. Wenn "none" angegeben wird, wird der Wert dieser Eigenschaft gelöscht.
keyVaultKeyName	string	Der Name Ihres Azure Key Vault-Schlüssels, der zum Verschlüsseln Ihrer ruhenden Daten verwendet werden soll.
keyVaultKeyVersion	string	Die Version Ihres Azure Key Vault-Schlüssels, der zum Verschlüsseln Ihrer ruhenden Daten verwendet werden soll.
keyVaultUri	string	Der URI Ihres Azure Key Vault, auch als DNS-Name bezeichnet, der den Schlüssel enthält, der zum Verschlüsseln Ihrer ruhenden Daten verwendet werden soll. Ein Beispiel-URI kann `https://my-keyvault-name.vault.azure.net`sein.