Knowledge Agents - Create

Služba:: Search Service

Verze rozhraní API:: 2025-08-01-preview

Vytvoří nového agenta.

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

Parametry identifikátoru URI

Název	V	Vyžadováno	Typ	Description
endpoint	path	True	string	Adresa URL koncového bodu vyhledávací služby.
api-version	query	True	string	Verze rozhraní API klienta.

Hlavička požadavku

Název	Vyžadováno	Typ	Description
x-ms-client-request-id		string (uuid)	ID sledování odeslané s požadavkem na pomoc s laděním.

Text požadavku

Název	Vyžadováno	Typ	Description
knowledgeSources	True	KnowledgeSourceReference[]
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Obsahuje možnosti konfigurace, jak se připojit k modelům AI.
name	True	string	Název znalostního agenta.
@odata.etag		string	Značka ETag agenta.
description		string	Popis agenta.
encryptionKey		SearchResourceEncryptionKey	Popis šifrovacího klíče, který vytvoříte v Azure Key Vault. Tento klíč se používá k poskytnutí další úrovně šifrování neaktivních uložených dat pro definici agenta, když chcete mít plnou jistotu, že je nikdo, ani Microsoft, nemůže dešifrovat. Jakmile definici agenta zašifrujete, zůstane vždy zašifrovaná. Vyhledávací služba bude ignorovat pokusy o nastavení této vlastnosti na hodnotu null. Tuto vlastnost můžete podle potřeby změnit, pokud chcete šifrovací klíč otočit; Definice agenta nebude ovlivněna. Šifrování pomocí klíčů spravovaných zákazníkem není k dispozici pro bezplatné vyhledávací služby a je k dispozici pouze pro placené služby vytvořené 1. ledna 2019 nebo později.
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	Mantinely pro omezení množství prostředků využitých pro jeden požadavek na načtení agenta.
retrievalInstructions		string	Pokyny, které agent znalostní báze bere v úvahu při vytváření plánu dotazů.

Odpovědi

Název	Typ	Description
201 Created	KnowledgeAgent	Úspěšně vytvořený agent
Other Status Codes	ErrorResponse	Chybová odpověď.

Příklady

SearchServiceCreateKnowledgeAgent

Ukázkový požadavek

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

Ukázková odpověď

Stavový kód:: 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>"
    }
  }
}

Definice

Název	Description
AzureActiveDirectoryApplicationCredentials	Přihlašovací údaje registrované aplikace vytvořené pro vaši vyhledávací službu, která se používá pro ověřený přístup k šifrovacím klíčům uloženým v Azure Key Vault.
AzureOpenAIEmbeddingSkill	Umožňuje vygenerovat vektorové vložení pro daný textový vstup pomocí prostředku Azure OpenAI.
AzureOpenAIModelName	Název modelu Azure Open AI, který se bude volat.
AzureOpenAIParameters	Určuje parametry pro připojení k prostředku Azure OpenAI.
ErrorAdditionalInfo	Další informace o chybě správy prostředků
ErrorDetail	Podrobnosti o chybě.
ErrorResponse	Chybová odpověď
InputFieldMappingEntry	Mapování vstupního pole pro dovednost.
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	Určuje prostředek Azure OpenAI používaný k plánování dotazů.
KnowledgeAgentModelKind	Model umělé inteligence, který se má použít pro plánování dotazů.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	Konfigurace výstupu pro agenta
KnowledgeAgentRequestLimits	Mantinely pro omezení množství prostředků využitých pro jeden požadavek na načtení agenta.
KnowledgeSourceReference
OutputFieldMappingEntry	Mapování výstupního pole pro dovednost.
SearchIndexerDataNoneIdentity	Vymaže vlastnost identity zdroje dat.
SearchIndexerDataUserAssignedIdentity	Určuje identitu zdroje dat, který se má použít.
SearchResourceEncryptionKey	Šifrovací klíč spravovaný zákazníkem ve službě Azure Key Vault. Klíče, které vytvoříte a spravujete, lze použít k šifrování nebo dešifrování neaktivních uložených dat, jako jsou indexy a mapy synonym.

AzureActiveDirectoryApplicationCredentials

Objekt

Přihlašovací údaje registrované aplikace vytvořené pro vaši vyhledávací službu, která se používá pro ověřený přístup k šifrovacím klíčům uloženým v Azure Key Vault.

Název	Typ	Description
applicationId	string	ID aplikace AAD, kterému byla udělena požadovaná přístupová oprávnění k Azure Key Vault, které se má použít při šifrování neaktivních uložených dat. ID aplikace by nemělo být zaměňováno s ID objektu pro vaši aplikaci AAD.
applicationSecret	string	Ověřovací klíč zadané aplikace AAD.

AzureOpenAIEmbeddingSkill

Objekt

Umožňuje vygenerovat vektorové vložení pro daný textový vstup pomocí prostředku Azure OpenAI.

Název	Typ	Description
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Fragment identifikátoru URI určující typ dovednosti.
apiKey	string	Klíč rozhraní API určeného prostředku Azure OpenAI.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Spravovaná identita přiřazená uživatelem používaná pro odchozí připojení.
context	string	Představuje úroveň, na které probíhají operace, jako je kořen dokumentu nebo obsah dokumentu (například /document nebo /document/content). Výchozí hodnota je /document.
deploymentId	string	ID nasazení modelu Azure OpenAI na určeném zdroji.
description	string	Popis dovednosti, který popisuje vstupy, výstupy a použití dovednosti.
dimensions	integer (int32)	Početdimenzích Podporováno pouze v modelech pro vkládání textu-3 a novějších.
inputs	InputFieldMappingEntry[]	Vstupy dovedností mohou být sloupec ve zdrojové datové sadě nebo výstup nadřazené dovednosti.
modelName	AzureOpenAIModelName	Název modelu vkládání, který je nasazen na zadané cestě deploymentId.
name	string	Název dovednosti, který ji v sadě dovedností jednoznačně identifikuje. Dovednost, která nemá definovaný žádný název, bude mít v poli dovedností výchozí název indexu založeného na hodnotě 1, kterému předchází znak #.
outputs	OutputFieldMappingEntry[]	Výstupem dovednosti je buď pole ve vyhledávacím indexu, nebo hodnota, která může být zpracována jako vstup jinou dovedností.
resourceUri	string (uri)	Identifikátor URI prostředku Azure OpenAI.

AzureOpenAIModelName

Výčet

Název modelu Azure Open AI, který se bude volat.

Hodnota	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

Objekt

Určuje parametry pro připojení k prostředku Azure OpenAI.

Název	Typ	Description
apiKey	string	Klíč rozhraní API určeného prostředku Azure OpenAI.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Spravovaná identita přiřazená uživatelem používaná pro odchozí připojení.
deploymentId	string	ID nasazení modelu Azure OpenAI na určeném zdroji.
modelName	AzureOpenAIModelName	Název modelu vkládání, který je nasazen na zadané cestě deploymentId.
resourceUri	string (uri)	Identifikátor URI prostředku Azure OpenAI.

ErrorAdditionalInfo

Objekt

Další informace o chybě správy prostředků

Název	Typ	Description
info	object	Další informace.
type	string	Další typ informací.

ErrorDetail

Objekt

Podrobnosti o chybě.

Název	Typ	Description
additionalInfo	ErrorAdditionalInfo[]	Další informace o chybě.
code	string	Kód chyby.
details	ErrorDetail[]	Podrobnosti o chybě.
message	string	Chybová zpráva.
target	string	Cíl chyby.

ErrorResponse

Objekt

Chybová odpověď

Název	Typ	Description
error	ErrorDetail	Objekt chyby.

InputFieldMappingEntry

Objekt

Mapování vstupního pole pro dovednost.

Název	Typ	Description
inputs	InputFieldMappingEntry[]	Rekurzivní vstupy používané při vytváření komplexního typu.
name	string	Název vstupu.
source	string	Zdroj vstupu.
sourceContext	string	Zdrojový kontext používaný pro výběr rekurzivních vstupů.

KnowledgeAgent

Objekt

Název	Typ	Description
@odata.etag	string	Značka ETag agenta.
description	string	Popis agenta.
encryptionKey	SearchResourceEncryptionKey	Popis šifrovacího klíče, který vytvoříte v Azure Key Vault. Tento klíč se používá k poskytnutí další úrovně šifrování neaktivních uložených dat pro definici agenta, když chcete mít plnou jistotu, že je nikdo, ani Microsoft, nemůže dešifrovat. Jakmile definici agenta zašifrujete, zůstane vždy zašifrovaná. Vyhledávací služba bude ignorovat pokusy o nastavení této vlastnosti na hodnotu null. Tuto vlastnost můžete podle potřeby změnit, pokud chcete šifrovací klíč otočit; Definice agenta nebude ovlivněna. Šifrování pomocí klíčů spravovaných zákazníkem není k dispozici pro bezplatné vyhledávací služby a je k dispozici pouze pro placené služby vytvořené 1. ledna 2019 nebo později.
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Obsahuje možnosti konfigurace, jak se připojit k modelům AI.
name	string	Název znalostního agenta.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Mantinely pro omezení množství prostředků využitých pro jeden požadavek na načtení agenta.
retrievalInstructions	string	Pokyny, které agent znalostní báze bere v úvahu při vytváření plánu dotazů.

KnowledgeAgentAzureOpenAIModel

Objekt

Určuje prostředek Azure OpenAI používaný k plánování dotazů.

Název	Typ	Description
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Obsahuje parametry specifické pro koncový bod modelu Azure OpenAI.
kind	string: azureOpenAI	Typ modelu AI.

KnowledgeAgentModelKind

Výčet

Model umělé inteligence, který se má použít pro plánování dotazů.

Hodnota	Description
azureOpenAI	K plánování dotazů používejte modely Azure Open AI.

KnowledgeAgentOutputConfiguration

Objekt

Název	Typ	Description
answerInstructions	string	Pokyny, které agent znalostí bere v úvahu při generování odpovědí
attemptFastPath	boolean	Označuje, zda se má agent pokusit odeslat nejnovější zprávu chatu jako přímý dotaz na zdroje znalostí a obejít volání modelu.
includeActivity	boolean	Označuje, že výsledky načítání by měly obsahovat informace o aktivitě.
modality	KnowledgeAgentOutputConfigurationModality	Konfigurace výstupu pro agenta

KnowledgeAgentOutputConfigurationModality

Výčet

Konfigurace výstupu pro agenta

Hodnota	Description
answerSynthesis	Syntetizuje odpověď pro datovou část odpovědi.
extractiveData	Vraťte data ze zdrojů znalostí přímo bez generativních změn.

KnowledgeAgentRequestLimits

Objekt

Mantinely pro omezení množství prostředků využitých pro jeden požadavek na načtení agenta.

Název	Typ	Description
maxOutputSize	integer (int32)	Omezuje maximální velikost obsahu ve výstupu.
maxRuntimeInSeconds	integer (int32)	Maximální doba běhu v sekundách.

KnowledgeSourceReference

Objekt

Název	Typ	Description
alwaysQuerySource	boolean	Označuje, že tento zdroj znalostí by měl obejít výběr zdroje a vždy se na něj dotazovat při načítání.
includeReferenceSourceData	boolean	Označuje, zda mají odkazy ve své datové části obsahovat strukturovaná data získaná během načítání.
includeReferences	boolean	Označuje, zda mají být zahrnuty odkazy pro data načtená z tohoto zdroje.
maxSubQueries	integer (int32)	Maximální počet dotazů, které mohou být vydány najednou při načítání dat z tohoto zdroje.
name	string	Název zdroje znalostí.
rerankerThreshold	number (float)	Prahová hodnota opětovného pořadí, kterou musí splňovat všechny načtené dokumenty, aby mohly být zahrnuty do odpovědi.

OutputFieldMappingEntry

Objekt

Mapování výstupního pole pro dovednost.

Název	Typ	Description
name	string	Název výstupu definovaného dovedností.
targetName	string	Cílový název výstupu. Je to volitelné a výchozí název.

SearchIndexerDataNoneIdentity

Objekt

Vymaže vlastnost identity zdroje dat.

Název	Typ	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Fragment identifikátoru URI určující typ identity.

SearchIndexerDataUserAssignedIdentity

Objekt

Určuje identitu zdroje dat, který se má použít.

Název	Typ	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Fragment identifikátoru URI určující typ identity.
userAssignedIdentity	string	Plně kvalifikované ID prostředku Azure spravované identity přiřazené uživatelem obvykle ve formátu "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId", které by mělo být přiřazeno vyhledávací službě.

SearchResourceEncryptionKey

Objekt

Šifrovací klíč spravovaný zákazníkem ve službě Azure Key Vault. Klíče, které vytvoříte a spravujete, lze použít k šifrování nebo dešifrování neaktivních uložených dat, jako jsou indexy a mapy synonym.

Název	Typ	Description
accessCredentials	AzureActiveDirectoryApplicationCredentials	Volitelné přihlašovací údaje Azure Active Directory používané pro přístup k Azure Key Vault. Není vyžadováno, pokud místo toho používáte spravovanou identitu.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Explicitní spravovaná identita, která se má použít pro tento šifrovací klíč. Pokud není zadán a vlastnost přístupových přihlašovacích údajů má hodnotu null, použije se spravovaná identita přiřazená systémem. Pokud při aktualizaci prostředku není explicitní identita určena, zůstane nezměněna. Pokud je zadáno "none", hodnota této vlastnosti je vymazána.
keyVaultKeyName	string	Název vašeho klíče Azure Key Vault, který se má použít k šifrování neaktivních uložených dat.
keyVaultKeyVersion	string	Verze klíče Azure Key Vault, která se má použít k šifrování neaktivních uložených dat.
keyVaultUri	string	Identifikátor URI vašeho Azure Key Vault, označovaný také jako název DNS, který obsahuje klíč, který se má použít k šifrování neaktivních uložených dat. Příkladem identifikátoru URI může být `https://my-keyvault-name.vault.azure.net`.