Knowledge Agents - Create

Dienst:: Search Service

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

Erstellt einen neuen Agent.

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

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
endpoint	path	True	string	Die Endpunkt-URL des Suchdiensts.
api-version	query	True	string	Version der Client-API.

Anforderungsheader

Name	Erforderlich	Typ	Beschreibung
x-ms-client-request-id		string (uuid)	Die Nachverfolgungs-ID, die mit der Anforderung gesendet wird, um das Debuggen zu unterstützen.

Anforderungstext

Name	Erforderlich	Typ	Beschreibung
knowledgeSources	True	KnowledgeSourceReference[]
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Enthält Konfigurationsoptionen zum Herstellen einer Verbindung mit KI-Modellen.
name	True	string	Der Name des Wissensagenten.
@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. Die Verschlüsselung mit kundenseitig verwalteten Schlüsseln ist für kostenlose Suchdienste nicht verfügbar und nur für kostenpflichtige Dienste, die am oder nach dem 1. Januar 2019 erstellt wurden.
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	Leitplanken, um zu begrenzen, wie viel Ressourcen für eine einzelne Agentenabrufanforderung verwendet werden.
retrievalInstructions		string	Anweisungen, die vom Knowledge Agent bei der Entwicklung eines Abfrageplans berücksichtigt werden.

Antworten

Name	Typ	Beschreibung
201 Created	KnowledgeAgent	Agent wurde erfolgreich erstellt.
Other Status Codes	ErrorResponse	Fehlerantwort.

Beispiele

SearchServiceCreateKnowledgeAgent

Beispielanforderung

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

Beispiel für eine Antwort

Statuscode:: 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>"
    }
  }
}

Definitionen

Name	Beschreibung
AzureActiveDirectoryApplicationCredentials	Anmeldeinformationen einer registrierten Anwendung, die für Ihren Suchdienst erstellt wurde und für den authentifizierten Zugriff auf die in Azure Key Vault gespeicherten Verschlüsselungsschlüssel verwendet wird.
AzureOpenAIEmbeddingSkill	Ermöglicht das Generieren einer Vektoreinbettung für eine bestimmte Texteingabe mithilfe der Azure OpenAI-Ressource.
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	Zuordnung von Eingabefeldern für einen Skill.
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.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	Die Ausgabekonfiguration für den Agenten
KnowledgeAgentRequestLimits	Leitplanken, um zu begrenzen, wie viel Ressourcen für eine einzelne Agentenabrufanforderung verwendet werden.
KnowledgeSourceReference
OutputFieldMappingEntry	Ausgabefeldzuordnung für einen Skill.
SearchIndexerDataNoneIdentity	Löscht die Identitätseigenschaft einer Datenquelle.
SearchIndexerDataUserAssignedIdentity	Gibt die Identität an, die von einer Datenquelle verwendet werden soll.
SearchResourceEncryptionKey	Ein kundenseitig verwalteter Verschlüsselungsschlüssel in 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 den authentifizierten Zugriff auf die in Azure Key Vault gespeicherten Verschlüsselungsschlüssel verwendet wird.

Name	Typ	Beschreibung
applicationId	string	Eine AAD-Anwendungs-ID, der die erforderlichen Zugriffsberechtigungen für Azure Key Vault erteilt wurden, die beim Verschlüsseln ruhender Daten verwendet werden soll. 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 das Generieren einer Vektoreinbettung für eine bestimmte Texteingabe mithilfe der Azure OpenAI-Ressource.

Name	Typ	Beschreibung
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Ein URI-Fragment, das den Typ des Skills angibt.
apiKey	string	API-Schlüssel der angegebenen Azure OpenAI-Ressource.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Die benutzerseitig 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 der Dokumentinhalt (z. B. /document oder /document/content). Der Standardwert ist /document.
deploymentId	string	ID der Bereitstellung des Azure OpenAI-Modells für die angegebene Ressource.
description	string	Die Beschreibung des Skills, die die Eingaben, Ausgaben und die Verwendung des Skills beschreibt.
dimensions	integer (int32)	Die Anzahl der Dimensionen, die die resultierenden Ausgabeeinbettungen aufweisen sollen. Wird nur in text-embedding-3 und höheren Modellen unterstützt.
inputs	InputFieldMappingEntry[]	Bei der Eingabe der Fertigkeiten kann es sich um eine Spalte im Quelldatensatz oder um die Ausgabe einer vorgelagerten Fertigkeit handeln.
modelName	AzureOpenAIModelName	Der Name des Einbettungsmodells, das unter dem angegebenen deploymentId-Pfad bereitgestellt wird.
name	string	Der Name des Skills, der ihn innerhalb des Skillssets eindeutig identifiziert. Ein Skill, für den kein Name definiert ist, erhält einen Standardnamen seines 1-basierten Index im skills-Array mit dem Präfix "#".
outputs	OutputFieldMappingEntry[]	Die Ausgabe eines Skills ist entweder ein Feld in einem Suchindex oder ein Wert, der von einem anderen Skill als Eingabe verwendet 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 benutzerseitig zugewiesene verwaltete Identität, die für ausgehende Verbindungen verwendet wird.
deploymentId	string	ID der Bereitstellung des Azure OpenAI-Modells für die angegebene Ressource.
modelName	AzureOpenAIModelName	Der Name des Einbettungsmodells, das unter dem angegebenen 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

Zuordnung von Eingabefeldern für einen Skill.

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. Die Verschlüsselung mit kundenseitig verwalteten Schlüsseln ist für kostenlose Suchdienste nicht verfügbar und nur für kostenpflichtige Dienste, die am oder nach dem 1. Januar 2019 erstellt wurden.
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Enthält Konfigurationsoptionen zum Herstellen einer Verbindung mit KI-Modellen.
name	string	Der Name des Wissensagenten.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Leitplanken, um zu begrenzen, wie viel Ressourcen für eine einzelne Agentenabrufanforderung verwendet werden.
retrievalInstructions	string	Anweisungen, die vom Knowledge Agent bei der Entwicklung eines Abfrageplans berücksichtigt werden.

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.

KnowledgeAgentOutputConfiguration

Objekt

Name	Typ	Beschreibung
answerInstructions	string	Anweisungen, die der Wissensagent bei der Generierung von Antworten berücksichtigt
attemptFastPath	boolean	Gibt an, ob der Agent versuchen soll, die neueste Chat-Nachricht als direkte Abfrage an die Wissensquellen auszugeben, wobei die Modellaufrufe umgangen werden.
includeActivity	boolean	Gibt an, dass die Abrufergebnisse Aktivitätsinformationen enthalten sollten.
modality	KnowledgeAgentOutputConfigurationModality	Die Ausgabekonfiguration für den Agenten

KnowledgeAgentOutputConfigurationModality

Enumeration

Die Ausgabekonfiguration für den Agenten

Wert	Beschreibung
answerSynthesis	Synthetisieren Sie eine Antwort für die Antwortnutzlast.
extractiveData	Geben Sie Daten aus den Wissensquellen direkt und ohne generative Änderung zurück.

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.

KnowledgeSourceReference

Objekt

Name	Typ	Beschreibung
alwaysQuerySource	boolean	Gibt an, dass diese Wissensquelle die Quellenauswahl umgehen und immer zum Zeitpunkt des Abrufs abgefragt werden soll.
includeReferenceSourceData	boolean	Gibt an, ob Verweise die strukturierten Daten, die während des Abrufs abgerufen wurden, in ihre Nutzlast aufnehmen sollen.
includeReferences	boolean	Gibt an, ob Verweise für Daten enthalten sein sollen, die aus dieser Quelle abgerufen werden.
maxSubQueries	integer (int32)	Die maximale Anzahl von Abfragen, die beim Abrufen von Daten aus dieser Quelle gleichzeitig ausgegeben werden können.
name	string	Der Name der Wissensquelle.
rerankerThreshold	number (float)	Der Reranker-Schwellenwert, den alle abgerufenen Dokumente erfüllen müssen, um in die Antwort aufgenommen zu werden.

OutputFieldMappingEntry

Objekt

Ausgabefeldzuordnung für einen Skill.

Name	Typ	Beschreibung
name	string	Der Name der Ausgabe, der durch den Skill definiert wird.
targetName	string	Der Zielname der Ausgabe. Es 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 Typ der Identität angibt.

SearchIndexerDataUserAssignedIdentity

Objekt

Gibt die Identität an, die von einer Datenquelle verwendet werden soll.

Name	Typ	Beschreibung
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Ein URI-Fragment, das den Typ der Identität angibt.
userAssignedIdentity	string	Die vollqualifizierte Azure-Ressourcen-ID einer benutzerseitig 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 hätte zugewiesen werden sollen.

SearchResourceEncryptionKey

Objekt

Ein kundenseitig verwalteter Verschlüsselungsschlüssel in 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. Nicht erforderlich, wenn stattdessen eine 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 nicht angegeben und die Eigenschaft für die Zugriffsanmeldeinformationen null ist, wird die systemseitig zugewiesene verwaltete Identität verwendet. Wenn die explizite Identität beim Aktualisieren der Ressource nicht angegeben ist, bleibt sie unverändert. Wenn "none" angegeben ist, wird der Wert dieser Eigenschaft gelöscht.
keyVaultKeyName	string	Der Name Ihres Azure Key Vault-Schlüssels, der zum Verschlüsseln ruhender Daten verwendet werden soll.
keyVaultKeyVersion	string	Die Version Ihres Azure Key Vault-Schlüssels, der zum Verschlüsseln ruhender Daten verwendet werden soll.
keyVaultUri	string	Der URI Ihres Azure Key Vault-Postfachs, der auch als DNS-Name bezeichnet wird und den Schlüssel enthält, der zum Verschlüsseln ruhender Daten verwendet werden soll. Ein Beispiel-URI könnte sein `https://my-keyvault-name.vault.azure.net`.