Knowledge Agents - Create Or Update

Szolgáltatás:: Search Service

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

Létrehoz egy új ügynököt, vagy frissít egy ügynököt, ha már létezik.

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

URI paraméterek

Név	Ban	Szükséges	Típus	Leírás
agentName	path	True	string	A létrehozni vagy frissíteni kívánt ügynök neve.
endpoint	path	True	string	A keresési szolgáltatás végponti 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 kéréssel együtt küldött nyomkövetési azonosító, amely segít a hibakeresésben.
If-Match		string	Meghatározza a If-Match feltételt. A művelet csak akkor lesz végrehajtva, ha a kiszolgálón lévő ETag megfelel ennek az értéknek.
If-None-Match		string	Meghatározza az If-None-Match feltételt. A művelet csak akkor lesz végrehajtva, ha a kiszolgálón lévő ETag nem egyezik meg ezzel az értékkel.
Prefer	True	string	HTTP PUT-kérések esetén utasítja a szolgáltatást, hogy a létrehozott/frissített erőforrást adja vissza a sikerhez.

Kérő Testület

Név	Szükséges	Típus	Leírás
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.
targetIndexes	True	KnowledgeAgentTargetIndex[]
@odata.etag		string	Az ügynök ETag-je.
description		string	Az ügynök leírása.
encryptionKey		SearchResourceEncryptionKey	Az Azure Key Vaultban 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 történő beá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 rendelkező 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.
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.

Válaszok

Név	Típus	Leírás
200 OK	KnowledgeAgent
201 Created	KnowledgeAgent
Other Status Codes	ErrorResponse	Hibaválasz.

Példák

SearchServiceCreateOrUpdateKnowledgeAgent

Mintakérés

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

Mintaválasz

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

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

Meghatározások

Név	Leírás
AzureActiveDirectoryApplicationCredentials	A keresési szolgáltatáshoz létrehozott regisztrált alkalmazás hitelesítő adatai, amelyeket az Azure Key Vaultban tárolt titkosítási kulcsokhoz való hitelesített hozzáféréshez használnak.
AzureOpenAIEmbeddingSkill	Lehetővé teszi egy vektor beágyazását egy adott szöveges bemenethez az Azure OpenAI-erőforrás használatával.
AzureOpenAIModelName	A meghívandó 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	Beviteli mező leképezése egy képességhez.
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.
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.
KnowledgeAgentTargetIndex
OutputFieldMappingEntry	Kimeneti mezőleképezés egy képességhez.
SearchIndexerDataNoneIdentity	Törli az adatforrás identitástulajdonsá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 kulcsokkal titkosíthatja vagy visszafejtheti az inaktív adatokat, például indexeket és szinonimatérképeket.

AzureActiveDirectoryApplicationCredentials

Tárgy

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

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 egy vektor beágyazását egy adott szöveges bemenethez az Azure OpenAI-erőforrás használatával.

Név	Típus	Leírás
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Egy URI-töredék, amely megadja a képesség típusát.
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 végrehajtásának szintjét jelöli, például a dokumentum gyökerét vagy a dokumentum 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épessé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észsé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évvel nem rendelkező képességek a képességtömb 1-alapú indexének alapértelmezett nevét kapják, "#" karakterrel előtaggal.
outputs	OutputFieldMappingEntry[]	A szakértelem kimenete vagy egy keresési index mezője, vagy egy olyan érték, amelyet egy másik képesség bemenetként használhat fel.
resourceUri	string (uri)	Az Azure OpenAI-erőforrás erőforrás-URI-ja.

AzureOpenAIModelName

Felsorolás

A meghívandó 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

Beviteli mező leképezése egy képességhez.

Név	Típus	Leírás
inputs	InputFieldMappingEntry[]	Az összetett 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	Az Azure Key Vaultban 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 történő beá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 rendelkező 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.
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.
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.
targetIndexes	KnowledgeAgentTargetIndex[]

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.

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.

KnowledgeAgentTargetIndex

Tárgy

Név	Típus	Leírás
defaultIncludeReferenceSourceData	boolean	Azt jelzi, hogy a referenciaforrás adatait bele kell-e foglalni.
defaultMaxDocsForReranker	integer (int32)	Korlátozza a rangsoroláshoz figyelembe vett dokumentumok számát.
defaultRerankerThreshold	number (float) minimum: 0 maximum: 4	Az eredmények újrarangsorolásának küszöbértéke (tartomány: 0–4).
indexName	string	A célindex neve.

OutputFieldMappingEntry

Tárgy

Kimeneti mezőleképezés egy képességhez.

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

SearchIndexerDataNoneIdentity

Tárgy

Törli az adatforrás identitástulajdonsá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 "/subscriptions/12345678-1234-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" formában található, 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 kulcsokkal titkosíthatja vagy visszafejtheti az inaktív adatokat, például indexeket és szinonimatérképeket.

Név	Típus	Leírás
accessCredentials	AzureActiveDirectoryApplicationCredentials	Az Azure Key Vault eléréséhez használt opcionális Azure Active Directory-hitelesítő adatok. Nem kötelező, ha ehelyett felügyelt identitást használ.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Explicit felügyelt identitás ehhez a titkosítási kulcshoz. Ha nincs megadva, és a hozzáférési hitelesítő adatok tulajdonság null értékű, akkor 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 meghatározva, az változatlan marad. Ha nincs megadva, a tulajdonság értéke törlődik.
keyVaultKeyName	string	A inaktív adatok titkosításához használandó Azure Key Vault-kulcs neve.
keyVaultKeyVersion	string	Az Azure Key Vault-kulcs inaktív adatok titkosításához használandó verziója.
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álandó kulcsot. Példa URI lehet `https://my-keyvault-name.vault.azure.net`.