Knowledge Agents - Create Or Update

Hizmet:: Search Service

API Sürümü:: 2025-05-01-preview

Yeni bir aracı oluşturur veya zaten varsa bir aracıyı güncelleştirir.

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

URI Parametreleri

Name	İçinde	Gerekli	Tür	Description
agentName	path	True	string	Oluşturulacak veya güncelleştirilecek aracının adı.
endpoint	path	True	string	Arama hizmetinin uç nokta URL'si.
api-version	query	True	string	İstemci Api Sürümü.

İstek Başlığı

Name	Gerekli	Tür	Description
x-ms-client-request-id		string (uuid)	Hata ayıklamaya yardımcı olmak için istekle birlikte gönderilen izleme kimliği.
If-Match		string	If-Match koşulunu tanımlar. İşlem yalnızca sunucudaki ETag bu değerle eşleşiyorsa gerçekleştirilir.
If-None-Match		string	If-None-Match koşulunu tanımlar. İşlem yalnızca sunucudaki ETag bu değerle eşleşmiyorsa gerçekleştirilir.
Prefer	True	string	HTTP PUT istekleri için, hizmete başarılı olduğunda oluşturulan/güncelleştirilen kaynağı döndürmesini bildirir.

İstek Gövdesi

Name	Gerekli	Tür	Description
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Yapay zeka modellerine nasıl bağlanılacağına ilişkin yapılandırma seçeneklerini içerir.
name	True	string	Bilgi aracısının adı.
targetIndexes	True	KnowledgeAgentTargetIndex[]
@odata.etag		string	Aracının ETag'i.
description		string	Aracının açıklaması.
encryptionKey		SearchResourceEncryptionKey	Azure Key Vault'ta oluşturduğunuz bir şifreleme anahtarının açıklaması. Bu anahtar, hiç kimsenin, hatta Microsoft'un bile şifresini çözemeyeceğinden tam olarak emin olmak istediğinizde, aracı tanımınız için ek bir bekleyen şifreleme düzeyi sağlamak için kullanılır. Aracı tanımınızı şifreledikten sonra, her zaman şifreli kalacaktır. Arama hizmeti bu özelliği null olarak ayarlama girişimlerini yoksayar. Şifreleme anahtarınızı döndürmek istiyorsanız bu özelliği gerektiği gibi değiştirebilirsiniz; Temsilci tanımınız etkilenmez. Müşteri tarafından yönetilen anahtarlarla şifreleme, ücretsiz arama hizmetlerinde kullanılamaz ve yalnızca 1 Ocak 2019 veya sonrasında oluşturulan ücretli hizmetler için kullanılabilir.
requestLimits		KnowledgeAgentRequestLimits	Tek bir aracı alma isteği için ne kadar kaynak kullanıldığını sınırlamak için korumalar.

Yanıtlar

Name	Tür	Description
200 OK	KnowledgeAgent
201 Created	KnowledgeAgent
Other Status Codes	ErrorResponse	Hata yanıtı.

Örnekler

SearchServiceCreateOrUpdateKnowledgeAgent

Örnek isteği

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

Örnek yanıt

Durum kodu:: 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>"
    }
  }
}

Durum kodu:: 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>"
    }
  }
}

Tanımlar

Name	Description
AzureActiveDirectoryApplicationCredentials	Arama hizmetiniz için oluşturulan ve Azure Key Vault'ta depolanan şifreleme anahtarlarına kimliği doğrulanmış erişim için kullanılan kayıtlı bir uygulamanın kimlik bilgileri.
AzureOpenAIEmbeddingSkill	Azure OpenAI kaynağını kullanarak belirli bir metin girişi için vektör ekleme oluşturmanızı sağlar.
AzureOpenAIModelName	Çağrılacak Azure Open AI modeli adı.
AzureOpenAIParameters	Azure OpenAI kaynağına bağlanmak için parametreleri belirtir.
ErrorAdditionalInfo	Kaynak yönetimi hatası ek bilgileri.
ErrorDetail	Hata ayrıntısı.
ErrorResponse	Hata yanıtı
InputFieldMappingEntry	Bir beceri için giriş alanı eşlemesi.
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	Sorgu planlaması yapmak için kullanılan Azure OpenAI kaynağını belirtir.
KnowledgeAgentModelKind	Sorgu planlaması için kullanılacak yapay zeka modeli.
KnowledgeAgentRequestLimits	Tek bir aracı alma isteği için ne kadar kaynak kullanıldığını sınırlamak için korumalar.
KnowledgeAgentTargetIndex
OutputFieldMappingEntry	Bir beceri için çıkış alanı eşlemesi.
SearchIndexerDataNoneIdentity	Veri kaynağının kimlik özelliğini temizler.
SearchIndexerDataUserAssignedIdentity	Kullanılacak veri kaynağının kimliğini belirtir.
SearchResourceEncryptionKey	Azure Key Vault'ta müşteri tarafından yönetilen bir şifreleme anahtarı. Oluşturduğunuz ve yönettiğiniz anahtarlar, dizinler ve eş anlamlı haritalar gibi bekleyen verileri şifrelemek veya şifresini çözmek için kullanılabilir.

AzureActiveDirectoryApplicationCredentials

Nesne

Arama hizmetiniz için oluşturulan ve Azure Key Vault'ta depolanan şifreleme anahtarlarına kimliği doğrulanmış erişim için kullanılan kayıtlı bir uygulamanın kimlik bilgileri.

Name	Tür	Description
applicationId	string	Bekleyen verilerinizi şifrelerken kullanılacak Azure Key Vault'a gerekli erişim izinleri verilmiş bir AAD Uygulama Kimliği. Uygulama Kimliği, AAD Uygulamanızın Nesne Kimliği ile karıştırılmamalıdır.
applicationSecret	string	Belirtilen AAD uygulamasının kimlik doğrulama anahtarı.

AzureOpenAIEmbeddingSkill

Nesne

Azure OpenAI kaynağını kullanarak belirli bir metin girişi için vektör ekleme oluşturmanızı sağlar.

Name	Tür	Description
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Beceri türünü belirten bir URI parçası.
apiKey	string	Belirlenen Azure OpenAI kaynağının API anahtarı.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Giden bağlantılar için kullanılan kullanıcı tarafından atanan yönetilen kimlik.
context	string	Belge kök veya belge içeriği (örneğin, /document veya /document/content) gibi işlemlerin gerçekleştiği düzeyi temsil eder. Varsayılan değer /document'dır.
deploymentId	string	Belirlenen kaynakta Azure OpenAI modeli dağıtımının kimliği.
description	string	Becerinin girişlerini, çıkışlarını ve kullanımını açıklayan becerinin açıklaması.
dimensions	integer (int32)	Sonuçta elde edilen çıktı eklemelerinin sahip olması gereken boyut sayısı. Yalnızca metin ekleme-3 ve üzeri modellerde desteklenir.
inputs	InputFieldMappingEntry[]	Becerilerin girişleri, kaynak veri kümesindeki bir sütun veya yukarı akış becerisinin çıkışı olabilir.
modelName	AzureOpenAIModelName	Sağlanan deploymentId yolunda dağıtılan ekleme modelinin adı.
name	string	Beceri kümesi içinde benzersiz olarak tanımlayan becerinin adı. Tanımlı adı olmayan bir beceriye beceri dizisinde 1 tabanlı dizininin varsayılan adı verilir ve bu ada '#' karakteri eklenir.
outputs	OutputFieldMappingEntry[]	Bir becerinin çıktısı, arama dizinindeki bir alan veya başka bir beceri tarafından giriş olarak kullanılabilecek bir değerdir.
resourceUri	string (uri)	Azure OpenAI kaynağının kaynak URI'si.

AzureOpenAIModelName

Numaralandırma

Çağrılacak Azure Open AI modeli adı.

Değer	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

Nesne

Azure OpenAI kaynağına bağlanmak için parametreleri belirtir.

Name	Tür	Description
apiKey	string	Belirlenen Azure OpenAI kaynağının API anahtarı.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Giden bağlantılar için kullanılan kullanıcı tarafından atanan yönetilen kimlik.
deploymentId	string	Belirlenen kaynakta Azure OpenAI modeli dağıtımının kimliği.
modelName	AzureOpenAIModelName	Sağlanan deploymentId yolunda dağıtılan ekleme modelinin adı.
resourceUri	string (uri)	Azure OpenAI kaynağının kaynak URI'si.

ErrorAdditionalInfo

Nesne

Kaynak yönetimi hatası ek bilgileri.

Name	Tür	Description
info	object	Ek bilgiler.
type	string	Ek bilgi türü.

ErrorDetail

Nesne

Hata ayrıntısı.

Name	Tür	Description
additionalInfo	ErrorAdditionalInfo[]	Hata ek bilgileri.
code	string	Hata kodu.
details	ErrorDetail[]	Hata ayrıntıları.
message	string	Hata iletisi.
target	string	Hata hedefi.

ErrorResponse

Nesne

Hata yanıtı

Name	Tür	Description
error	ErrorDetail	Hata nesnesi.

InputFieldMappingEntry

Nesne

Bir beceri için giriş alanı eşlemesi.

Name	Tür	Description
inputs	InputFieldMappingEntry[]	Karmaşık bir tür oluştururken kullanılan özyinelemeli girişler.
name	string	Girişin adı.
source	string	Girişin kaynağı.
sourceContext	string	Özyinelemeli girişleri seçmek için kullanılan kaynak bağlam.

KnowledgeAgent

Nesne

Name	Tür	Description
@odata.etag	string	Aracının ETag'i.
description	string	Aracının açıklaması.
encryptionKey	SearchResourceEncryptionKey	Azure Key Vault'ta oluşturduğunuz bir şifreleme anahtarının açıklaması. Bu anahtar, hiç kimsenin, hatta Microsoft'un bile şifresini çözemeyeceğinden tam olarak emin olmak istediğinizde, aracı tanımınız için ek bir bekleyen şifreleme düzeyi sağlamak için kullanılır. Aracı tanımınızı şifreledikten sonra, her zaman şifreli kalacaktır. Arama hizmeti bu özelliği null olarak ayarlama girişimlerini yoksayar. Şifreleme anahtarınızı döndürmek istiyorsanız bu özelliği gerektiği gibi değiştirebilirsiniz; Temsilci tanımınız etkilenmez. Müşteri tarafından yönetilen anahtarlarla şifreleme, ücretsiz arama hizmetlerinde kullanılamaz ve yalnızca 1 Ocak 2019 veya sonrasında oluşturulan ücretli hizmetler için kullanılabilir.
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Yapay zeka modellerine nasıl bağlanılacağına ilişkin yapılandırma seçeneklerini içerir.
name	string	Bilgi aracısının adı.
requestLimits	KnowledgeAgentRequestLimits	Tek bir aracı alma isteği için ne kadar kaynak kullanıldığını sınırlamak için korumalar.
targetIndexes	KnowledgeAgentTargetIndex[]

KnowledgeAgentAzureOpenAIModel

Nesne

Sorgu planlaması yapmak için kullanılan Azure OpenAI kaynağını belirtir.

Name	Tür	Description
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Azure OpenAI model uç noktasına özgü parametreleri içerir.
kind	string: azureOpenAI	Yapay zeka modelinin türü.

KnowledgeAgentModelKind

Numaralandırma

Sorgu planlaması için kullanılacak yapay zeka modeli.

Değer	Description
azureOpenAI	Sorgu planlaması için Azure Open AI modellerini kullanın.

KnowledgeAgentRequestLimits

Nesne

Tek bir aracı alma isteği için ne kadar kaynak kullanıldığını sınırlamak için korumalar.

Name	Tür	Description
maxOutputSize	integer (int32)	Çıktıdaki içeriğin maksimum boyutunu sınırlar.
maxRuntimeInSeconds	integer (int32)	Saniye cinsinden maksimum çalışma zamanı.

KnowledgeAgentTargetIndex

Nesne

Name	Tür	Description
defaultIncludeReferenceSourceData	boolean	Başvuru kaynağı verilerinin dahil edilip edilmeyeceğini belirtir.
defaultMaxDocsForReranker	integer (int32)	Sıralama için dikkate alınan belge sayısını sınırlar.
defaultRerankerThreshold	number (float) minimum: 0 maximum: 4	Sonuçları yeniden sıralamak için bir eşik (aralık: 0-4).
indexName	string	Hedef dizinin adı.

OutputFieldMappingEntry

Nesne

Bir beceri için çıkış alanı eşlemesi.

Name	Tür	Description
name	string	Beceri tarafından tanımlanan çıkışın adı.
targetName	string	Çıkışın hedef adı. İsteğe bağlıdır ve varsayılan addır.

SearchIndexerDataNoneIdentity

Nesne

Veri kaynağının kimlik özelliğini temizler.

Name	Tür	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Kimlik türünü belirten bir URI parçası.

SearchIndexerDataUserAssignedIdentity

Nesne

Kullanılacak veri kaynağının kimliğini belirtir.

Name	Tür	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Kimlik türünü belirten bir URI parçası.
userAssignedIdentity	string	Kullanıcı tarafından atanan yönetilen kimliğin tam Azure kaynak kimliği genellikle arama hizmetine atanması gereken "/subscriptions/12345678-1234-1234-1234-123467890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" biçimindedir.

SearchResourceEncryptionKey

Nesne

Azure Key Vault'ta müşteri tarafından yönetilen bir şifreleme anahtarı. Oluşturduğunuz ve yönettiğiniz anahtarlar, dizinler ve eş anlamlı haritalar gibi bekleyen verileri şifrelemek veya şifresini çözmek için kullanılabilir.

Name	Tür	Description
accessCredentials	AzureActiveDirectoryApplicationCredentials	Azure Key Vault'unuza erişmek için kullanılan isteğe bağlı Azure Active Directory kimlik bilgileri. Bunun yerine yönetilen kimlik kullanılıyorsa gerekli değildir.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Bu şifreleme anahtarı için kullanılacak açık bir yönetilen kimlik. Belirtilmezse ve erişim kimlik bilgileri özelliği null ise, sistem tarafından atanan yönetilen kimlik kullanılır. Kaynağa güncelleştirildiğinde, açık kimlik belirtilmezse değişmeden kalır. "Hiçbiri" belirtilirse, bu özelliğin değeri temizlenir.
keyVaultKeyName	string	Bekleyen verilerinizi şifrelemek için kullanılacak Azure Key Vault anahtarınızın adı.
keyVaultKeyVersion	string	Bekleyen verilerinizi şifrelemek için kullanılacak Azure Key Vault anahtarınızın sürümü.
keyVaultUri	string	Bekleyen verilerinizi şifrelemek için kullanılacak anahtarı içeren, DNS adı olarak da adlandırılan Azure Key Vault URI'sidir. Örnek bir URI `https://my-keyvault-name.vault.azure.net`olabilir.