Knowledge Agents - Create Or Update

Layanan:: Search Service

Versi API:: 2025-08-01-preview

Membuat agen baru atau memperbarui agen jika sudah ada.

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

Parameter URI

Nama	Dalam	Diperlukan	Jenis	Deskripsi
agentName	path	True	string	Nama agen yang akan dibuat atau diperbarui.
endpoint	path	True	string	URL titik akhir layanan pencarian.
api-version	query	True	string	Versi API Klien.

Header Permintaan

Nama	Diperlukan	Jenis	Deskripsi
x-ms-client-request-id		string (uuid)	ID pelacakan yang dikirim dengan permintaan untuk membantu penelusuran kesalahan.
If-Match		string	Menentukan kondisi If-Match. Operasi akan dilakukan hanya jika ETag di server cocok dengan nilai ini.
If-None-Match		string	Menentukan kondisi If-None-Match. Operasi akan dilakukan hanya jika ETag di server tidak cocok dengan nilai ini.
Prefer	True	string	Untuk permintaan HTTP PUT, menginstruksikan layanan untuk mengembalikan sumber daya yang dibuat/diperbarui setelah berhasil.

Isi Permintaan

Nama	Diperlukan	Jenis	Deskripsi
knowledgeSources	True	KnowledgeSourceReference[]
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Berisi opsi konfigurasi tentang cara terhubung ke model AI.
name	True	string	Nama agen pengetahuan.
@odata.etag		string	ETag agen.
description		string	Penjabaran dari agen.
encryptionKey		SearchResourceEncryptionKey	Deskripsi kunci enkripsi yang Anda buat di Azure Key Vault. Kunci ini digunakan untuk memberikan tingkat enkripsi tambahan untuk definisi agen Anda ketika Anda menginginkan jaminan penuh bahwa tidak ada seorang pun, bahkan Microsoft, yang dapat mendekripsinya. Setelah Anda mengenkripsi definisi agen Anda, itu akan selalu terenkripsi. Layanan pencarian akan mengabaikan upaya untuk mengatur properti ini ke null. Anda dapat mengubah properti ini sesuai kebutuhan jika Anda ingin memutar kunci enkripsi Anda; Definisi agen Anda tidak akan terpengaruh. Enkripsi dengan kunci yang dikelola pelanggan tidak tersedia untuk layanan penelusuran gratis, dan hanya tersedia untuk layanan berbayar yang dibuat pada atau setelah 1 Januari 2019.
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	Pagar pembatas untuk membatasi berapa banyak sumber daya yang digunakan untuk satu permintaan pengambilan agen.
retrievalInstructions		string	Instruksi yang dipertimbangkan oleh agen pengetahuan saat mengembangkan rencana kueri.

Respons

Nama	Jenis	Deskripsi
200 OK	KnowledgeAgent
201 Created	KnowledgeAgent
Other Status Codes	ErrorResponse	Respons kesalahan.

Contoh

SearchServiceCreateOrUpdateKnowledgeAgent

Permintaan sampel

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

Respon sampel

Kode status:: 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>"
    }
  }
}

Kode status:: 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>"
    }
  }
}

Definisi

Nama	Deskripsi
AzureActiveDirectoryApplicationCredentials	Kredensial aplikasi terdaftar yang dibuat untuk layanan pencarian Anda, digunakan untuk akses terautentikasi ke kunci enkripsi yang disimpan di Azure Key Vault.
AzureOpenAIEmbeddingSkill	Memungkinkan Anda membuat penyematan vektor untuk input teks tertentu menggunakan sumber daya Azure OpenAI.
AzureOpenAIModelName	Nama model Azure Open AI yang akan dipanggil.
AzureOpenAIParameters	Menentukan parameter untuk menyambungkan ke sumber daya Azure OpenAI.
ErrorAdditionalInfo	Info tambahan kesalahan manajemen sumber daya.
ErrorDetail	Detail kesalahan.
ErrorResponse	Tanggapan kesalahan
InputFieldMappingEntry	Pemetaan bidang input untuk keterampilan.
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	Menentukan sumber daya Azure OpenAI yang digunakan untuk melakukan perencanaan kueri.
KnowledgeAgentModelKind	Model AI yang akan digunakan untuk perencanaan kueri.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	Konfigurasi output untuk agen
KnowledgeAgentRequestLimits	Pagar pembatas untuk membatasi berapa banyak sumber daya yang digunakan untuk satu permintaan pengambilan agen.
KnowledgeSourceReference
OutputFieldMappingEntry	Pemetaan bidang keluaran untuk keterampilan.
SearchIndexerDataNoneIdentity	Menghapus properti identitas sumber data.
SearchIndexerDataUserAssignedIdentity	Menentukan identitas untuk digunakan sumber data.
SearchResourceEncryptionKey	Kunci enkripsi yang dikelola pelanggan di Azure Key Vault. Kunci yang Anda buat dan kelola dapat digunakan untuk mengenkripsi atau mendekripsi data-at-rest, seperti indeks dan peta sinonim.

AzureActiveDirectoryApplicationCredentials

Objek

Kredensial aplikasi terdaftar yang dibuat untuk layanan pencarian Anda, digunakan untuk akses terautentikasi ke kunci enkripsi yang disimpan di Azure Key Vault.

Nama	Jenis	Deskripsi
applicationId	string	ID Aplikasi AAD yang diberikan izin akses yang diperlukan ke Azure Key Vault yang akan digunakan saat mengenkripsi data Anda saat tidak aktif. ID Aplikasi tidak boleh disamakan dengan ID Objek untuk Aplikasi AAD Anda.
applicationSecret	string	Kunci otentikasi dari aplikasi AAD yang ditentukan.

AzureOpenAIEmbeddingSkill

Objek

Memungkinkan Anda membuat penyematan vektor untuk input teks tertentu menggunakan sumber daya Azure OpenAI.

Nama	Jenis	Deskripsi
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Fragmen URI yang menentukan jenis keterampilan.
apiKey	string	Kunci API dari sumber daya Azure OpenAI yang ditunjuk.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identitas terkelola yang ditetapkan pengguna yang digunakan untuk koneksi keluar.
context	string	Mewakili tingkat di mana operasi berlangsung, seperti akar dokumen atau konten dokumen (misalnya, /document atau /document/content). Defaultnya adalah /document.
deploymentId	string	ID penyebaran model Azure OpenAI pada sumber daya yang ditentukan.
description	string	Deskripsi keterampilan yang menggambarkan input, output, dan penggunaan keterampilan.
dimensions	integer (int32)	Jumlah dimensi yang harus dimiliki oleh embedding output yang dihasilkan. Hanya didukung dalam text-embedding-3 dan model yang lebih baru.
inputs	InputFieldMappingEntry[]	Input keterampilan dapat berupa kolom dalam kumpulan data sumber, atau output dari keterampilan hulu.
modelName	AzureOpenAIModelName	Nama model penyematan yang disebarkan di jalur deploymentId yang disediakan.
name	string	Nama keterampilan yang secara unik mengidentifikasinya dalam keahlian. Keterampilan tanpa nama yang ditentukan akan diberi nama default dari indeks berbasis 1 dalam array keterampilan, diawali dengan karakter '#'.
outputs	OutputFieldMappingEntry[]	Output keterampilan adalah bidang dalam indeks pencarian, atau nilai yang dapat digunakan sebagai input oleh keterampilan lain.
resourceUri	string (uri)	URI sumber daya sumber daya Azure OpenAI.

AzureOpenAIModelName

Enumerasi

Nama model Azure Open AI yang akan dipanggil.

Nilai	Deskripsi
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

Objek

Menentukan parameter untuk menyambungkan ke sumber daya Azure OpenAI.

Nama	Jenis	Deskripsi
apiKey	string	Kunci API dari sumber daya Azure OpenAI yang ditunjuk.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identitas terkelola yang ditetapkan pengguna yang digunakan untuk koneksi keluar.
deploymentId	string	ID penyebaran model Azure OpenAI pada sumber daya yang ditentukan.
modelName	AzureOpenAIModelName	Nama model penyematan yang disebarkan di jalur deploymentId yang disediakan.
resourceUri	string (uri)	URI sumber daya sumber daya Azure OpenAI.

ErrorAdditionalInfo

Objek

Info tambahan kesalahan manajemen sumber daya.

Nama	Jenis	Deskripsi
info	object	Info tambahan.
type	string	Jenis info tambahan.

ErrorDetail

Objek

Detail kesalahan.

Nama	Jenis	Deskripsi
additionalInfo	ErrorAdditionalInfo[]	Info tambahan kesalahan.
code	string	Kode kesalahan.
details	ErrorDetail[]	Detail kesalahan.
message	string	Pesan kesalahan.
target	string	Target kesalahan.

ErrorResponse

Objek

Tanggapan kesalahan

Nama	Jenis	Deskripsi
error	ErrorDetail	Objek kesalahan.

InputFieldMappingEntry

Objek

Pemetaan bidang input untuk keterampilan.

Nama	Jenis	Deskripsi
inputs	InputFieldMappingEntry[]	Input rekursif yang digunakan saat membuat jenis yang kompleks.
name	string	Nama input.
source	string	Sumber input.
sourceContext	string	Konteks sumber yang digunakan untuk memilih input rekursif.

KnowledgeAgent

Objek

Nama	Jenis	Deskripsi
@odata.etag	string	ETag agen.
description	string	Penjabaran dari agen.
encryptionKey	SearchResourceEncryptionKey	Deskripsi kunci enkripsi yang Anda buat di Azure Key Vault. Kunci ini digunakan untuk memberikan tingkat enkripsi tambahan untuk definisi agen Anda ketika Anda menginginkan jaminan penuh bahwa tidak ada seorang pun, bahkan Microsoft, yang dapat mendekripsinya. Setelah Anda mengenkripsi definisi agen Anda, itu akan selalu terenkripsi. Layanan pencarian akan mengabaikan upaya untuk mengatur properti ini ke null. Anda dapat mengubah properti ini sesuai kebutuhan jika Anda ingin memutar kunci enkripsi Anda; Definisi agen Anda tidak akan terpengaruh. Enkripsi dengan kunci yang dikelola pelanggan tidak tersedia untuk layanan penelusuran gratis, dan hanya tersedia untuk layanan berbayar yang dibuat pada atau setelah 1 Januari 2019.
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Berisi opsi konfigurasi tentang cara terhubung ke model AI.
name	string	Nama agen pengetahuan.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Pagar pembatas untuk membatasi berapa banyak sumber daya yang digunakan untuk satu permintaan pengambilan agen.
retrievalInstructions	string	Instruksi yang dipertimbangkan oleh agen pengetahuan saat mengembangkan rencana kueri.

KnowledgeAgentAzureOpenAIModel

Objek

Menentukan sumber daya Azure OpenAI yang digunakan untuk melakukan perencanaan kueri.

Nama	Jenis	Deskripsi
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Berisi parameter khusus untuk titik akhir model Azure OpenAI.
kind	string: azureOpenAI	Jenis model AI.

KnowledgeAgentModelKind

Enumerasi

Model AI yang akan digunakan untuk perencanaan kueri.

Nilai	Deskripsi
azureOpenAI	Gunakan model Azure Open AI untuk perencanaan kueri.

KnowledgeAgentOutputConfiguration

Objek

Nama	Jenis	Deskripsi
answerInstructions	string	Instruksi yang dipertimbangkan oleh agen pengetahuan saat menghasilkan jawaban
attemptFastPath	boolean	Menunjukkan apakah agen harus mencoba mengeluarkan pesan obrolan terbaru sebagai kueri langsung ke sumber pengetahuan, melewati panggilan model.
includeActivity	boolean	Menunjukkan hasil pengambilan harus menyertakan informasi aktivitas.
modality	KnowledgeAgentOutputConfigurationModality	Konfigurasi output untuk agen

KnowledgeAgentOutputConfigurationModality

Enumerasi

Konfigurasi output untuk agen

Nilai	Deskripsi
answerSynthesis	Mensintesis jawaban untuk payload respons.
extractiveData	Mengembalikan data dari sumber pengetahuan secara langsung tanpa perubahan generatif.

KnowledgeAgentRequestLimits

Objek

Pagar pembatas untuk membatasi berapa banyak sumber daya yang digunakan untuk satu permintaan pengambilan agen.

Nama	Jenis	Deskripsi
maxOutputSize	integer (int32)	Membatasi ukuran maksimum konten dalam output.
maxRuntimeInSeconds	integer (int32)	Runtime maksimum dalam hitungan detik.

KnowledgeSourceReference

Objek

Nama	Jenis	Deskripsi
alwaysQuerySource	boolean	Menunjukkan bahwa sumber pengetahuan ini harus melewati pemilihan sumber dan selalu dikueri pada waktu pengambilan.
includeReferenceSourceData	boolean	Menunjukkan apakah referensi harus menyertakan data terstruktur yang diperoleh selama pengambilan dalam payload mereka.
includeReferences	boolean	Menunjukkan apakah referensi harus disertakan untuk data yang diambil dari sumber ini.
maxSubQueries	integer (int32)	Jumlah maksimum kueri yang dapat dikeluarkan pada satu waktu saat mengambil data dari sumber ini.
name	string	Nama sumber pengetahuan.
rerankerThreshold	number (float)	Ambang batas reranker yang harus dipenuhi semua dokumen yang diambil untuk disertakan dalam respons.

OutputFieldMappingEntry

Objek

Pemetaan bidang keluaran untuk keterampilan.

Nama	Jenis	Deskripsi
name	string	Nama output yang ditentukan oleh keterampilan.
targetName	string	Nama target output. Ini opsional dan default untuk bernama.

SearchIndexerDataNoneIdentity

Objek

Menghapus properti identitas sumber data.

Nama	Jenis	Deskripsi
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Fragmen URI yang menentukan jenis identitas.

SearchIndexerDataUserAssignedIdentity

Objek

Menentukan identitas untuk digunakan sumber data.

Nama	Jenis	Deskripsi
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Fragmen URI yang menentukan jenis identitas.
userAssignedIdentity	string	Id sumber daya Azure yang memenuhi syarat penuh dari identitas terkelola yang ditetapkan pengguna biasanya dalam bentuk "/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" yang seharusnya ditetapkan ke layanan pencarian.

SearchResourceEncryptionKey

Objek

Kunci enkripsi yang dikelola pelanggan di Azure Key Vault. Kunci yang Anda buat dan kelola dapat digunakan untuk mengenkripsi atau mendekripsi data-at-rest, seperti indeks dan peta sinonim.

Nama	Jenis	Deskripsi
accessCredentials	AzureActiveDirectoryApplicationCredentials	Kredensial Azure Active Directory opsional yang digunakan untuk mengakses Azure Key Vault Anda. Tidak diperlukan jika menggunakan identitas terkelola sebagai gantinya.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identitas terkelola eksplisit untuk digunakan untuk kunci enkripsi ini. Jika tidak ditentukan dan properti kredensial akses null, identitas terkelola yang ditetapkan sistem digunakan. Saat memperbarui sumber daya, jika identitas eksplisit tidak ditentukan, identitas tersebut tetap tidak berubah. Jika "none" ditentukan, nilai properti ini dihapus.
keyVaultKeyName	string	Nama kunci Azure Key Vault Anda yang akan digunakan untuk mengenkripsi data Anda saat tidak aktif.
keyVaultKeyVersion	string	Versi kunci Azure Key Vault Anda yang akan digunakan untuk mengenkripsi data Anda saat tidak aktif.
keyVaultUri	string	URI Azure Key Vault Anda, juga disebut sebagai nama DNS, yang berisi kunci yang akan digunakan untuk mengenkripsi data Anda saat tidak aktif. Contoh URI mungkin .`https://my-keyvault-name.vault.azure.net`