Knowledge Agents - Create Or Update

Hizmet:: Search Service

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

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

PUT {endpoint}/agents('{agentName}')?api-version=2025-08-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şirse gerçekleştirilir.
If-None-Match		string	If-None-Match koşulunu tanımlar. İşlem yalnızca sunucudaki ETag bu değerle eşleşmezse 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 söyler.

İstek Gövdesi

Name	Gerekli	Tür	Description
knowledgeSources	True	KnowledgeSourceReference[]
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ı.
@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 hizmetleri için kullanılamaz ve yalnızca 1 Ocak 2019'da veya sonrasında oluşturulan ücretli hizmetler için kullanılabilir.
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	Tek bir aracı alma isteği için ne kadar kaynak kullanıldığını sınırlamak için korumalar.
retrievalInstructions		string	Sorgu planı geliştirilirken bilgi aracısı tarafından dikkate alınan yönergeler.

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-08-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"
    }
  ],
  "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."
}

Örnek yanıt

Durum kodu:: 200

{
  "@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-4o-mini"
      }
    }
  ],
  "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>"
    }
  }
}

Durum kodu:: 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-4o-mini"
      }
    }
  ],
  "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>"
    }
  }
}

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 bir vektör eklemesi oluşturmanıza olanak tanır.
AzureOpenAIModelName	Çağrılacak Azure Open AI model 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.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	Aracının çıkış yapılandırması
KnowledgeAgentRequestLimits	Tek bir aracı alma isteği için ne kadar kaynak kullanıldığını sınırlamak için korumalar.
KnowledgeSourceReference
OutputFieldMappingEntry	Bir beceri için çıktı alanı eşlemesi.
SearchIndexerDataNoneIdentity	Bir 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ı eşlemeler 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 için 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 bir vektör eklemesi oluşturmanıza olanak tanır.

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'dir.
deploymentId	string	Belirlenen kaynakta Azure OpenAI modeli dağıtımının kimliği.
description	string	Becerinin girdilerini, çıktı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 text-embedding-3 ve sonraki modellerde desteklenir.
inputs	InputFieldMappingEntry[]	Becerilerin girişleri, kaynak veri kümesindeki bir sütun veya yukarı akış becerisinin çıktısı olabilir.
modelName	AzureOpenAIModelName	Sağlanan deploymentId yolunda dağıtılan katıştırma modelinin adı.
name	string	Becerinin, onu beceri kümesi içinde benzersiz bir şekilde tanımlayan adı. Adı tanımlanmamış bir beceriye, beceriler dizisindeki 1 tabanlı dizininin varsayılan adı verilir ve önüne '#' karakteri eklenir.
outputs	OutputFieldMappingEntry[]	Bir becerinin çıktısı, arama dizinindeki bir alan veya başka bir beceri tarafından girdi 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 model 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 katıştırma 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 hizmetleri için kullanılamaz ve yalnızca 1 Ocak 2019'da veya sonrasında oluşturulan ücretli hizmetler için kullanılabilir.
knowledgeSources	KnowledgeSourceReference[]
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ı.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Tek bir aracı alma isteği için ne kadar kaynak kullanıldığını sınırlamak için korumalar.
retrievalInstructions	string	Sorgu planı geliştirilirken bilgi aracısı tarafından dikkate alınan yönergeler.

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.

KnowledgeAgentOutputConfiguration

Nesne

Name	Tür	Description
answerInstructions	string	Cevaplar oluşturulurken bilgi aracısı tarafından dikkate alınan talimatlar
attemptFastPath	boolean	Aracının, model çağrılarını atlayarak en son sohbet iletisini bilgi kaynaklarına doğrudan sorgu olarak göndermeye çalışıp çalışmayacağını belirtir.
includeActivity	boolean	Alma sonuçlarının etkinlik bilgilerini içermesi gerektiğini belirtir.
modality	KnowledgeAgentOutputConfigurationModality	Aracının çıkış yapılandırması

KnowledgeAgentOutputConfigurationModality

Numaralandırma

Aracının çıkış yapılandırması

Değer	Description
answerSynthesis	Yanıt yükü için bir yanıt sentezleyin.
extractiveData	Üretimsel değişiklik yapmadan doğrudan bilgi kaynaklarından veri döndürü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ı.

KnowledgeSourceReference

Nesne

Name	Tür	Description
alwaysQuerySource	boolean	Bu bilgi kaynağının kaynak seçimini atlaması ve alma zamanında her zaman sorgulanması gerektiğini gösterir.
includeReferenceSourceData	boolean	Başvuruların, alma sırasında elde edilen yapılandırılmış verileri yüklerine dahil edip etmeyeceğini belirtir.
includeReferences	boolean	Bu kaynaktan alınan veriler için başvuruların dahil edilip edilmeyeceğini belirtir.
maxSubQueries	integer (int32)	Bu kaynaktan veri alınırken bir kerede verilebilecek en fazla sorgu sayısı.
name	string	Bilgi kaynağının adı.
rerankerThreshold	number (float)	Yanıta dahil edilmek için alınan tüm belgelerin karşılaması gereken yeniden sıralayıcı eşiği.

OutputFieldMappingEntry

Nesne

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

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

SearchIndexerDataNoneIdentity

Nesne

Bir 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	Genellikle "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" biçiminde yönetilen kimlik atanan bir kullanıcının tam Azure kaynak kimliği.

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ı eşlemeler gibi bekleyen verileri şifrelemek veya şifresini çözmek için kullanılabilir.

Name	Tür	Description
accessCredentials	AzureActiveDirectoryApplicationCredentials	Azure Key Vault 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. Kaynak güncelleştirildiğinde, açık kimlik belirtilmemişse değişmeden kalır. "None" 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	DNS adı olarak da adlandırılan Azure Key Vault URI'si, bekleyen verilerinizi şifrelemek için kullanılacak anahtarı içerir. Örnek bir URI olabilir `https://my-keyvault-name.vault.azure.net`.