Knowledge Agents - Create

Szolgáltatás:: Search Service

API verzió:: 2025-08-01-preview

Létrehoz egy új ügynököt.

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

URI paraméterek

Név	Ban	Szükséges	Típus	Leírás
endpoint	path	True	string	A keresési szolgáltatás végpontjának URL-címe.
api-version	query	True	string	Ügyfél API verziója.

Kérés fejléce

Név	Szükséges	Típus	Leírás
x-ms-client-request-id		string (uuid)	A hibakeresési kérelemmel küldött nyomkövetési azonosító.

Kérő Testület

Név	Szükséges	Típus	Leírás
knowledgeSources	True	KnowledgeSourceReference[]
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Konfigurációs beállításokat tartalmaz az AI-modellekhez való csatlakozáshoz.
name	True	string	A tudásügynök neve.
@odata.etag		string	Az ügynök ETag-je.
description		string	Az ügynök leírása.
encryptionKey		SearchResourceEncryptionKey	A Azure Key Vault létrehozott titkosítási kulcs leírása. Ez a kulcs az inaktív adatok titkosításának további szintjét biztosítja az ügynökdefinícióhoz, ha teljes körű biztosítékot szeretne arra, hogy senki, még a Microsoft sem tudja visszafejteni őket. Miután titkosította az ügynök definícióját, az mindig titkosítva marad. A keresési szolgáltatás figyelmen kívül hagyja a tulajdonság null értékre állítására tett kísérleteket. Ezt a tulajdonságot szükség szerint módosíthatja, ha el szeretné forgatni a titkosítási kulcsot; Az ügynök definícióját ez nem érinti. Az ügyfél által felügyelt kulcsokkal való titkosítás nem érhető el az ingyenes keresési szolgáltatásokhoz, és csak a 2019. január 1-jén vagy azt követően létrehozott fizetős szolgáltatásokhoz érhető el.
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	Védőkorlátok az egyetlen ügynök lekérési kéréséhez használt erőforrások mennyiségének korlátozására.
retrievalInstructions		string	A tudásügynök által a lekérdezési terv kidolgozása során figyelembe vett utasítások.

Válaszok

Név	Típus	Leírás
201 Created	KnowledgeAgent	Sikeresen létrehozott egy ügynököt
Other Status Codes	ErrorResponse	Hibaválasz.

Példák

SearchServiceCreateKnowledgeAgent

Mintakérés

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

Mintaválasz

Állapotkó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>"
    }
  }
}

Meghatározások

Név	Leírás
AzureActiveDirectoryApplicationCredentials	A keresési szolgáltatáshoz létrehozott regisztrált alkalmazás hitelesítő adatai, amelyek a Azure Key Vault tárolt titkosítási kulcsokhoz való hitelesített hozzáféréshez használatosak.
AzureOpenAIEmbeddingSkill	Lehetővé teszi vektoros beágyazás létrehozását egy adott szövegbevitelhez az Azure OpenAI-erőforrás használatával.
AzureOpenAIModelName	A meghívott Azure Open AI-modell neve.
AzureOpenAIParameters	Megadja az Azure OpenAI-erőforráshoz való csatlakozás paramétereit.
ErrorAdditionalInfo	Az erőforrás-kezelési hiba további információi.
ErrorDetail	A hiba részletei.
ErrorResponse	Hibaválasz
InputFieldMappingEntry	Képesség beviteli mezőjének leképezése.
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	Megadja a lekérdezések tervezéséhez használt Azure OpenAI-erőforrást.
KnowledgeAgentModelKind	A lekérdezések tervezéséhez használt AI-modell.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	Az ügynök kimeneti konfigurációja
KnowledgeAgentRequestLimits	Védőkorlátok az egyetlen ügynök lekérési kéréséhez használt erőforrások mennyiségének korlátozására.
KnowledgeSourceReference
OutputFieldMappingEntry	Képesség kimeneti mezőleképezése.
SearchIndexerDataNoneIdentity	Törli egy adatforrás identity tulajdonságát.
SearchIndexerDataUserAssignedIdentity	Megadja a használni kívánt adatforrás identitását.
SearchResourceEncryptionKey	Ügyfél által felügyelt titkosítási kulcs az Azure Key Vaultban. A létrehozott és kezelt kulcsok az inaktív adatok, például az indexek és a szinonimatérképek titkosítására vagy visszafejtésére használhatók.

AzureActiveDirectoryApplicationCredentials

Tárgy

A keresési szolgáltatáshoz létrehozott regisztrált alkalmazás hitelesítő adatai, amelyek a Azure Key Vault tárolt titkosítási kulcsokhoz való hitelesített hozzáféréshez használatosak.

Név	Típus	Leírás
applicationId	string	Egy AAD-alkalmazásazonosító, amely megkapta a szükséges hozzáférési engedélyeket az Azure Key Vaulthoz, amelyet az inaktív adatok titkosításához kell használni. Az alkalmazásazonosító nem tévesztendő össze az AAD-alkalmazás objektumazonosítójával.
applicationSecret	string	A megadott AAD-alkalmazás hitelesítési kulcsa.

AzureOpenAIEmbeddingSkill

Tárgy

Lehetővé teszi vektoros beágyazás létrehozását egy adott szövegbevitelhez az Azure OpenAI-erőforrás használatával.

Név	Típus	Leírás
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	A képesség típusát meghatározó URI-töredék.
apiKey	string	A kijelölt Azure OpenAI-erőforrás API-kulcsa.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	A kimenő kapcsolatokhoz használt, felhasználó által hozzárendelt felügyelt identitás.
context	string	A műveletek szintjét jelöli, például a dokumentum gyökerét vagy tartalmát (például /document vagy /document/content). Az alapértelmezett érték a /document.
deploymentId	string	Az Azure OpenAI-modell üzembe helyezésének azonosítója a kijelölt erőforráson.
description	string	A készség leírása, amely leírja a képesség bemeneteit, kimeneteit és használatát.
dimensions	integer (int32)	Az eredményként kapott kimeneti beágyazások dimenzióinak száma. Csak a text-embedding-3 és újabb modellekben támogatott.
inputs	InputFieldMappingEntry[]	A képességek bemenetei lehetnek a forrásadatkészlet oszlopai vagy egy felsőbb rétegbeli képesség kimenete.
modelName	AzureOpenAIModelName	A megadott deploymentId elérési úton üzembe helyezett beágyazási modell neve.
name	string	Annak a képességnek a neve, amely egyedileg azonosítja azt a képességkészleten belül. A név nélküli képességek alapértelmezett nevet kapnak az 1-alapú indexhez a képességtömbben, a "#" karakter előtaggal.
outputs	OutputFieldMappingEntry[]	A képesség kimenete vagy egy keresési index mezője, vagy egy másik képesség által bemenetként felhasznált érték.
resourceUri	string (uri)	Az Azure OpenAI-erőforrás erőforrás-URI-ja.

AzureOpenAIModelName

Felsorolás

A meghívott Azure Open AI-modell neve.

Érték	Leírás
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

Tárgy

Megadja az Azure OpenAI-erőforráshoz való csatlakozás paramétereit.

Név	Típus	Leírás
apiKey	string	A kijelölt Azure OpenAI-erőforrás API-kulcsa.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	A kimenő kapcsolatokhoz használt, felhasználó által hozzárendelt felügyelt identitás.
deploymentId	string	Az Azure OpenAI-modell üzembe helyezésének azonosítója a kijelölt erőforráson.
modelName	AzureOpenAIModelName	A megadott deploymentId elérési úton üzembe helyezett beágyazási modell neve.
resourceUri	string (uri)	Az Azure OpenAI-erőforrás erőforrás-URI-ja.

ErrorAdditionalInfo

Tárgy

Az erőforrás-kezelési hiba további információi.

Név	Típus	Leírás
info	object	A további információk.
type	string	A további információtípus.

ErrorDetail

Tárgy

A hiba részletei.

Név	Típus	Leírás
additionalInfo	ErrorAdditionalInfo[]	A hiba további információi.
code	string	A hibakód.
details	ErrorDetail[]	A hiba részletei.
message	string	A hibaüzenet.
target	string	A hibacél.

ErrorResponse

Tárgy

Hibaválasz

Név	Típus	Leírás
error	ErrorDetail	A hibaobjektum.

InputFieldMappingEntry

Tárgy

Képesség beviteli mezőjének leképezése.

Név	Típus	Leírás
inputs	InputFieldMappingEntry[]	A komplex típus létrehozásakor használt rekurzív bemenetek.
name	string	A bemenet neve.
source	string	A bemenet forrása.
sourceContext	string	A rekurzív bemenetek kiválasztásához használt forráskörnyezet.

KnowledgeAgent

Tárgy

Név	Típus	Leírás
@odata.etag	string	Az ügynök ETag-je.
description	string	Az ügynök leírása.
encryptionKey	SearchResourceEncryptionKey	A Azure Key Vault létrehozott titkosítási kulcs leírása. Ez a kulcs az inaktív adatok titkosításának további szintjét biztosítja az ügynökdefinícióhoz, ha teljes körű biztosítékot szeretne arra, hogy senki, még a Microsoft sem tudja visszafejteni őket. Miután titkosította az ügynök definícióját, az mindig titkosítva marad. A keresési szolgáltatás figyelmen kívül hagyja a tulajdonság null értékre állítására tett kísérleteket. Ezt a tulajdonságot szükség szerint módosíthatja, ha el szeretné forgatni a titkosítási kulcsot; Az ügynök definícióját ez nem érinti. Az ügyfél által felügyelt kulcsokkal való titkosítás nem érhető el az ingyenes keresési szolgáltatásokhoz, és csak a 2019. január 1-jén vagy azt követően létrehozott fizetős szolgáltatásokhoz érhető el.
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Konfigurációs beállításokat tartalmaz az AI-modellekhez való csatlakozáshoz.
name	string	A tudásügynök neve.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Védőkorlátok az egyetlen ügynök lekérési kéréséhez használt erőforrások mennyiségének korlátozására.
retrievalInstructions	string	A tudásügynök által a lekérdezési terv kidolgozása során figyelembe vett utasítások.

KnowledgeAgentAzureOpenAIModel

Tárgy

Megadja a lekérdezések tervezéséhez használt Azure OpenAI-erőforrást.

Név	Típus	Leírás
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Az Azure OpenAI-modell végpontjára jellemző paramétereket tartalmazza.
kind	string: azureOpenAI	Az AI-modell típusa.

KnowledgeAgentModelKind

Felsorolás

A lekérdezések tervezéséhez használt AI-modell.

Érték	Leírás
azureOpenAI	Lekérdezéstervezéshez használja az Azure Open AI-modelleket.

KnowledgeAgentOutputConfiguration

Tárgy

Név	Típus	Leírás
answerInstructions	string	A tudásügynök által a válaszok generálásakor figyelembe vett utasítások
attemptFastPath	boolean	Azt jelzi, hogy az ügynöknek meg kell-e kísérelnie a legutóbbi csevegőüzenetet közvetlen lekérdezésként kiadni a tudásforrásoknak, megkerülve a modellhívásokat.
includeActivity	boolean	Azt jelzi, hogy a lekérési eredményeknek tartalmazniuk kell a tevékenység adatait.
modality	KnowledgeAgentOutputConfigurationModality	Az ügynök kimeneti konfigurációja

KnowledgeAgentOutputConfigurationModality

Felsorolás

Az ügynök kimeneti konfigurációja

Érték	Leírás
answerSynthesis	Szintetizáljon egy választ a válasz hasznos adataira.
extractiveData	Adatok visszaadása a tudásforrásokból közvetlenül, generatív módosítás nélkül.

KnowledgeAgentRequestLimits

Tárgy

Védőkorlátok az egyetlen ügynök lekérési kéréséhez használt erőforrások mennyiségének korlátozására.

Név	Típus	Leírás
maxOutputSize	integer (int32)	Korlátozza a kimenet tartalmának maximális méretét.
maxRuntimeInSeconds	integer (int32)	A maximális futási idő másodpercben.

KnowledgeSourceReference

Tárgy

Név	Típus	Leírás
alwaysQuerySource	boolean	Azt jelzi, hogy ennek a tudásforrásnak meg kell kerülnie a forrás kiválasztását, és mindig le kell kérdeznie a lekéréskor.
includeReferenceSourceData	boolean	Azt jelzi, hogy a hivatkozásoknak tartalmazniuk kell-e a lekérés során kapott strukturált adatokat a hasznos adatokban.
includeReferences	boolean	Azt jelzi, hogy a forrásból beolvasott adatokhoz kell-e hivatkozásokat is belefoglalni.
maxSubQueries	integer (int32)	Az egyszerre kibocsátható lekérdezések maximális száma, amikor adatokat kér le ebből a forrásból.
name	string	A tudásforrás neve.
rerankerThreshold	number (float)	Az újrarangsoroló küszöbértéke, amelyet minden lekért dokumentumnak meg kell felelnie ahhoz, hogy szerepeljen a válaszban.

OutputFieldMappingEntry

Tárgy

Képesség kimeneti mezőleképezése.

Név	Típus	Leírás
name	string	A képesség által meghatározott kimenet neve.
targetName	string	A kimenet célneve. Ez nem kötelező, és alapértelmezés szerint a név.

SearchIndexerDataNoneIdentity

Tárgy

Törli egy adatforrás identity tulajdonságát.

Név	Típus	Leírás
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Az identitás típusát meghatározó URI-töredék.

SearchIndexerDataUserAssignedIdentity

Tárgy

Megadja a használni kívánt adatforrás identitását.

Név	Típus	Leírás
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Az identitás típusát meghatározó URI-töredék.
userAssignedIdentity	string	A felhasználó által hozzárendelt felügyelt identitás teljes Azure-erőforrás-azonosítója, általában a következő formátumban: "/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId", amelyet hozzá kellett volna rendelni a keresési szolgáltatáshoz.

SearchResourceEncryptionKey

Tárgy

Ügyfél által felügyelt titkosítási kulcs az Azure Key Vaultban. A létrehozott és kezelt kulcsok az inaktív adatok, például az indexek és a szinonimatérképek titkosítására vagy visszafejtésére használhatók.

Név	Típus	Leírás
accessCredentials	AzureActiveDirectoryApplicationCredentials	A Azure Key Vault eléréséhez használt opcionális Azure Active Directory hitelesítő adatok. Nem szükséges, ha felügyelt identitást használ.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	A titkosítási kulcshoz használandó explicit felügyelt identitás. Ha nincs megadva, és a hozzáférési hitelesítő adatok tulajdonsága null, a rendszer a rendszer által hozzárendelt felügyelt identitást használja. Az erőforrás frissítésekor, ha az explicit identitás nincs megadva, az változatlan marad. Ha a "nincs" van megadva, a tulajdonság értéke törlődik.
keyVaultKeyName	string	Az inaktív adatok titkosításához használt Azure Key Vault kulcs neve.
keyVaultKeyVersion	string	Az Azure Key Vault kulcs verziója, amely az inaktív adatok titkosításához használható.
keyVaultUri	string	Az Azure Key Vault URI-ja, más néven DNS-név, amely tartalmazza az inaktív adatok titkosításához használt kulcsot. Példa lehet az URI-ra `https://my-keyvault-name.vault.azure.net`.