Knowledge Agents - Create Or Update

服務:: Search Service

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

創建新代理或更新代理（如果已存在）。

PUT {endpoint}/agents('{agentName}')?api-version=2025-05-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)	隨要求一起傳送的追蹤標識碼，以協助偵錯。
If-Match		string	定義 If-Match 條件。只有在伺服器上的 ETag 符合此值時，才會執行此作業。
If-None-Match		string	定義 If-None-Match 條件。只有在伺服器上的 ETag 不符合此值時，才會執行此作業。
Prefer	True	string	針對 HTTP PUT 要求，指示服務在成功時傳回已建立/更新的資源。

要求本文

名稱	必要	類型	Description
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	包含有關如何連接到 AI 模型的配置選項。
name	True	string	知識代理的名稱。
targetIndexes	True	KnowledgeAgentTargetIndex[]
@odata.etag		string	代理的 ETag。
description		string	代理程式的描述。
encryptionKey		SearchResourceEncryptionKey	您在 Azure Key Vault 中建立的加密金鑰描述。當您希望完全保證沒有人（甚至 Microsoft）可以解密它們時，此密鑰用於為您的代理定義提供額外的靜態加密級別。加密代理定義后，它將始終保持加密狀態。搜尋服務會忽略將此屬性設定為 null 的嘗試。如果要輪換加密金鑰，您可以根據需要更改此屬性;您的代理定義將不受影響。使用客戶管理的金鑰加密不適用於免費搜尋服務，而且僅適用於 2019 年 1 月 1 日或之後建立的付費服務。
requestLimits		KnowledgeAgentRequestLimits	防護機制來限制單個代理檢索請求使用的資源量。

回應

名稱	類型	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-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."
}

範例回覆

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

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

定義

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

AzureActiveDirectoryApplicationCredentials

Object

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

名稱	類型	Description
applicationId	string	AAD 應用程式識別碼，已將待用數據加密時要使用的 Azure Key Vault 所需訪問許可權授與。應用程式標識碼不應與 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)	產生的輸出內嵌應具有的維度數目。只有文字內嵌-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 Key Vault 中建立的加密金鑰描述。當您希望完全保證沒有人（甚至 Microsoft）可以解密它們時，此密鑰用於為您的代理定義提供額外的靜態加密級別。加密代理定義后，它將始終保持加密狀態。搜尋服務會忽略將此屬性設定為 null 的嘗試。如果要輪換加密金鑰，您可以根據需要更改此屬性;您的代理定義將不受影響。使用客戶管理的金鑰加密不適用於免費搜尋服務，而且僅適用於 2019 年 1 月 1 日或之後建立的付費服務。
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	包含有關如何連接到 AI 模型的配置選項。
name	string	知識代理的名稱。
requestLimits	KnowledgeAgentRequestLimits	防護機制來限制單個代理檢索請求使用的資源量。
targetIndexes	KnowledgeAgentTargetIndex[]

KnowledgeAgentAzureOpenAIModel

Object

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

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

KnowledgeAgentModelKind

列舉型別

用於查詢規劃的 AI 模型。

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

KnowledgeAgentRequestLimits

Object

防護機制來限制單個代理檢索請求使用的資源量。

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

KnowledgeAgentTargetIndex

Object

名稱	類型	Description
defaultIncludeReferenceSourceData	boolean	指示是否應包含引用源數據。
defaultMaxDocsForReranker	integer (int32)	限制考慮進行排名的文件數量。
defaultRerankerThreshold	number (float) minimum: 0 maximum: 4	重新排名結果的閾值（範圍：0-4）。
indexName	string	目標索引的名稱。

OutputFieldMappingEntry

Object

技能的輸出欄位對應。

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

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-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId”。

SearchResourceEncryptionKey

Object

Azure Key Vault 中客戶管理的加密密鑰。您建立和管理的金鑰可用來加密或解密待用數據，例如索引和同義字對應。

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