Knowledge Agents - Create Or Update

服務:: Search Service

API 版本:: 2025-08-01-preview

建立新的代理程式或更新代理程式（如果已存在）。

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

URI 參數

名稱	位於	必要	類型	Description
agentName	path	True	string	要建立或更新的代理程式名稱。
endpoint	path	True	string	搜尋服務的端點 URL。
api-version	query	True	string	用戶端 API 版本。

要求標頭

名稱	必要	類型	Description
x-ms-client-request-id		string (uuid)	隨請求一起傳送的追蹤 ID，以協助偵錯。
If-Match		string	定義 If-Match 條件。只有在伺服器上的 ETag 符合此值時，才會執行作業。
If-None-Match		string	定義 If-None-Match 條件。只有在伺服器上的 ETag 不符合此值時，才會執行作業。
Prefer	True	string	針對 HTTP PUT 要求，指示服務在成功時傳回建立/更新的資源。

要求本文

名稱	必要	類型	Description
knowledgeSources	True	KnowledgeSourceReference[]
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	包含有關如何連接到 AI 模型的配置選項。
name	True	string	知識代理程式的名稱。
@odata.etag		string	代理程式的 ETag。
description		string	代理程式的描述。
encryptionKey		SearchResourceEncryptionKey	您在 Azure 金鑰保存庫中建立的加密金鑰描述。當您想要完全保證沒有人（甚至 Microsoft）無法解密它們時，此金鑰可用來為您的代理程式定義提供額外的待用加密層級。加密代理程式定義後，它將始終保持加密狀態。搜尋服務會忽略嘗試將此屬性設定為 Null。如果您想要輪替加密金鑰，您可以視需要變更此屬性;您的代理定義將不受影響。使用客戶管理的金鑰進行加密不適用於免費搜尋服務，且僅適用於 2019 年 1 月 1 日或之後建立的付費服務。
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	限制單一代理程式擷取請求使用的資源量的護欄。
retrievalInstructions		string	知識代理程式在開發查詢計劃時所考慮的指示。

回應

名稱	類型	Description
200 OK	KnowledgeAgent
201 Created	KnowledgeAgent
Other Status Codes	ErrorResponse	錯誤回應。

範例

SearchServiceCreateOrUpdateKnowledgeAgent

範例要求

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

範例回覆

狀態碼:: 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>"
    }
  }
}

狀態碼:: 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>"
    }
  }
}

定義

名稱	Description
AzureActiveDirectoryApplicationCredentials	針對搜尋服務建立之已註冊應用程式認證，用於對儲存在 Azure 金鑰保存庫中的加密金鑰進行驗證存取。
AzureOpenAIEmbeddingSkill	可讓您使用 Azure OpenAI 資源為指定的文字輸入產生向量內嵌。
AzureOpenAIModelName	將呼叫的 Azure Open AI 模型名稱。
AzureOpenAIParameters	指定連線到 Azure OpenAI 資源的參數。
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細數據。
ErrorResponse	錯誤回應
InputFieldMappingEntry	技能的輸入欄位對應。
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	指定用來執行查詢規劃的 Azure OpenAI 資源。
KnowledgeAgentModelKind	要用於查詢規劃的 AI 模型。
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	代理程式的輸出組態
KnowledgeAgentRequestLimits	限制單一代理程式擷取請求使用的資源量的護欄。
KnowledgeSourceReference
OutputFieldMappingEntry	技能的輸出欄位對應。
SearchIndexerDataNoneIdentity	清除資料來源的身分識別屬性。
SearchIndexerDataUserAssignedIdentity	指定要使用的資料來源身分識別。
SearchResourceEncryptionKey	Azure Key Vault 中的客戶管理加密金鑰。您建立和管理的金鑰可用來加密或解密靜態資料，例如索引和同義字對映。

AzureActiveDirectoryApplicationCredentials

Object

針對搜尋服務建立之已註冊應用程式認證，用於對儲存在 Azure 金鑰保存庫中的加密金鑰進行驗證存取。

名稱	類型	Description
applicationId	string	已授與 Azure 金鑰保存庫所需存取權限的 AAD 應用程式識別碼，可在加密待用資料時使用。應用程式識別碼不應與 AAD 應用程式的物件識別碼混淆。
applicationSecret	string	指定 AAD 應用程式的驗證金鑰。

AzureOpenAIEmbeddingSkill

Object

可讓您使用 Azure OpenAI 資源為指定的文字輸入產生向量內嵌。

名稱	類型	Description
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	指定技能類型的 URI 片段。
apiKey	string	指定 Azure OpenAI 資源的 API 金鑰。
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	用於輸出連線的使用者指派受控識別。
context	string	代表作業發生的層級，例如文件根目錄或文件內容（例如，/document 或 /document/content）。預設值為 /document。
deploymentId	string	指定資源上 Azure OpenAI 模型部署的識別碼。
description	string	技能的描述，描述技能的輸入、輸出和使用方式。
dimensions	integer (int32)	產生的輸出內嵌應具有的維度數目。僅在 text-embedding-3 和更新版本中支援。
inputs	InputFieldMappingEntry[]	技能的輸入可以是來源資料集中的資料行，也可以是上游技能的輸出。
modelName	AzureOpenAIModelName	部署在提供的 deploymentId 路徑上的內嵌模型名稱。
name	string	在技能集中唯一識別技能的技能名稱。未定義名稱的技能將在技能陣列中獲得其從 1 開始的索引的預設名稱，並以字元「#」為前綴。
outputs	OutputFieldMappingEntry[]	技能的輸出是搜尋索引中的欄位，或可作為另一個技能輸入使用的值。
resourceUri	string (uri)	Azure OpenAI 資源的資源 URI。

AzureOpenAIModelName

列舉型別

將呼叫的 Azure Open AI 模型名稱。

值	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

Object

指定連線到 Azure OpenAI 資源的參數。

名稱	類型	Description
apiKey	string	指定 Azure OpenAI 資源的 API 金鑰。
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	用於輸出連線的使用者指派受控識別。
deploymentId	string	指定資源上 Azure OpenAI 模型部署的識別碼。
modelName	AzureOpenAIModelName	部署在提供的 deploymentId 路徑上的內嵌模型名稱。
resourceUri	string (uri)	Azure OpenAI 資源的資源 URI。

ErrorAdditionalInfo

Object

資源管理錯誤其他資訊。

名稱	類型	Description
info	object	其他資訊。
type	string	其他信息類型。

ErrorDetail

Object

錯誤詳細數據。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤其他資訊。
code	string	錯誤碼。
details	ErrorDetail[]	錯誤詳細資料。
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorResponse

Object

錯誤回應

名稱	類型	Description
error	ErrorDetail	error 物件。

InputFieldMappingEntry

Object

技能的輸入欄位對應。

名稱	類型	Description
inputs	InputFieldMappingEntry[]	建立複雜類型時使用的遞迴輸入。
name	string	輸入的名稱。
source	string	輸入的來源。
sourceContext	string	用於選取遞迴輸入的來源內容。

KnowledgeAgent

Object

名稱	類型	Description
@odata.etag	string	代理程式的 ETag。
description	string	代理程式的描述。
encryptionKey	SearchResourceEncryptionKey	您在 Azure 金鑰保存庫中建立的加密金鑰描述。當您想要完全保證沒有人（甚至 Microsoft）無法解密它們時，此金鑰可用來為您的代理程式定義提供額外的待用加密層級。加密代理程式定義後，它將始終保持加密狀態。搜尋服務會忽略嘗試將此屬性設定為 Null。如果您想要輪替加密金鑰，您可以視需要變更此屬性;您的代理定義將不受影響。使用客戶管理的金鑰進行加密不適用於免費搜尋服務，且僅適用於 2019 年 1 月 1 日或之後建立的付費服務。
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	包含有關如何連接到 AI 模型的配置選項。
name	string	知識代理程式的名稱。
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	限制單一代理程式擷取請求使用的資源量的護欄。
retrievalInstructions	string	知識代理程式在開發查詢計劃時所考慮的指示。

KnowledgeAgentAzureOpenAIModel

Object

指定用來執行查詢規劃的 Azure OpenAI 資源。

名稱	類型	Description
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	包含 Azure OpenAI 模型端點特有的參數。
kind	string: azureOpenAI	AI 模型的類型。

KnowledgeAgentModelKind

列舉型別

要用於查詢規劃的 AI 模型。

值	Description
azureOpenAI	使用 Azure Open AI 模型進行查詢規劃。

KnowledgeAgentOutputConfiguration

Object

名稱	類型	Description
answerInstructions	string	知識代理程式在產生答案時所考慮的指示
attemptFastPath	boolean	指出客服專員是否應嘗試將最新的聊天訊息作為對知識來源的直接查詢，略過模型呼叫。
includeActivity	boolean	表示擷取結果應包含活動資訊。
modality	KnowledgeAgentOutputConfigurationModality	代理程式的輸出組態

KnowledgeAgentOutputConfigurationModality

列舉型別

代理程式的輸出組態

值	Description
answerSynthesis	合成回應承載的答案。
extractiveData	直接從知識來源傳回資料，無需生成式變更。

KnowledgeAgentRequestLimits

Object

限制單一代理程式擷取請求使用的資源量的護欄。

名稱	類型	Description
maxOutputSize	integer (int32)	限制輸出中內容的大小上限。
maxRuntimeInSeconds	integer (int32)	執行時間上限（以秒為單位）。

KnowledgeSourceReference

Object

名稱	類型	Description
alwaysQuerySource	boolean	表示此知識來源應該略過來源選取，並一律在擷取時進行查詢。
includeReferenceSourceData	boolean	指出參照是否應該在其承載中包含擷取期間取得的結構化資料。
includeReferences	boolean	指出是否應包含從此來源擷取的資料的參考。
maxSubQueries	integer (int32)	從此來源擷取資料時，一次可發出的查詢數目上限。
name	string	知識來源的名稱。
rerankerThreshold	number (float)	所有擷取的文件都必須符合重新排序器臨界值，才能包含在回應中。

OutputFieldMappingEntry

Object

技能的輸出欄位對應。

名稱	類型	Description
name	string	技能所定義的輸出名稱。
targetName	string	輸出的目標名稱。它是選用的，預設為名稱。

SearchIndexerDataNoneIdentity

Object

清除資料來源的身分識別屬性。

名稱	類型	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	指定身分類型的 URI 片段。

SearchIndexerDataUserAssignedIdentity

Object

指定要使用的資料來源身分識別。

名稱	類型	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	指定身分類型的 URI 片段。
userAssignedIdentity	string	使用者指派受控識別的完整 Azure 資源識別碼，通常採用「/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId」格式，應該已指派給搜尋服務。

SearchResourceEncryptionKey

Object

Azure Key Vault 中的客戶管理加密金鑰。您建立和管理的金鑰可用來加密或解密靜態資料，例如索引和同義字對映。

名稱	類型	Description
accessCredentials	AzureActiveDirectoryApplicationCredentials	用來存取 Azure 金鑰保存庫的選擇性 Azure Active Directory 認證。如果改用受控識別，則不需要。
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	用於此加密金鑰的明確受控識別。如果未指定且存取認證屬性為 Null，則會使用系統指派的受控識別。更新資源時，如果未指定明確身分識別，則會保持不變。如果指定 “none” ，則會清除此屬性的值。
keyVaultKeyName	string	要用來加密待用資料的 Azure 金鑰保存庫名稱。
keyVaultKeyVersion	string	要用來加密待用資料的 Azure 金鑰版本。
keyVaultUri	string	Azure 金鑰保存庫的 URI，也稱為 DNS 名稱，其中包含要用來加密待用資料的金鑰。範例 URI 可能是 `https://my-keyvault-name.vault.azure.net`。