你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Knowledge Agents - Create Or Update

参考

服务:: Search Service

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

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

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

URI 参数

名称	在	必需	类型	说明
agentName	path	True	string	要创建或更新的代理的名称。
endpoint	path	True	string	搜索服务的终结点 URL。
api-version	query	True	string	客户端 API 版本。

请求头

名称	必需	类型	说明
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 请求，指示服务在成功时返回已创建/更新的资源。

请求正文

名称	必需	类型	说明
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	防护机制来限制单个代理检索请求使用的资源量。

响应

名称	类型	说明
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>"
    }
  }
}

定义

名称	说明
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 中存储的加密密钥进行身份验证的访问权限。

名称	类型	说明
applicationId	string	向 AAD 应用程序 ID 授予对静态数据加密时要使用的 Azure Key Vault 所需的访问权限。应用程序 ID 不应与 AAD 应用程序的对象 ID 混淆。
applicationSecret	string	指定的 AAD 应用程序的身份验证密钥。

AzureOpenAIEmbeddingSkill

Object

允许使用 Azure OpenAI 资源为给定文本输入生成矢量嵌入。

名称	类型	说明
@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 模型部署的 ID。
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 模型名称。

值	说明
gpt-4.1
gpt-4.1-mini
gpt-4.1-nano
gpt-4o
gpt-4o-mini
text-embedding-3-large
text-embedding-3-small
text-embedding-ada-002

AzureOpenAIParameters

Object

指定用于连接到 Azure OpenAI 资源的参数。

名称	类型	说明
apiKey	string	指定的 Azure OpenAI 资源的 API 密钥。
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	用于出站连接的用户分配的托管标识。
deploymentId	string	指定资源上的 Azure OpenAI 模型部署的 ID。
modelName	AzureOpenAIModelName	在提供的 deploymentId 路径中部署的嵌入模型的名称。
resourceUri	string (uri)	Azure OpenAI 资源的资源 URI。

ErrorAdditionalInfo

Object

资源管理错误附加信息。

名称	类型	说明
info	object	其他信息。
type	string	其他信息类型。

ErrorDetail

Object

错误详细信息。

名称	类型	说明
additionalInfo	ErrorAdditionalInfo[]	错误附加信息。
code	string	错误代码。
details	ErrorDetail[]	错误详细信息。
message	string	错误消息。
target	string	错误目标。

ErrorResponse

Object

错误响应

名称	类型	说明
error	ErrorDetail	错误对象。

InputFieldMappingEntry

Object

技能的输入字段映射。

名称	类型	说明
inputs	InputFieldMappingEntry[]	创建复杂类型时使用的递归输入。
name	string	输入的名称。
source	string	输入的源。
sourceContext	string	用于选择递归输入的源上下文。

KnowledgeAgent

Object

名称	类型	说明
@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 资源。

名称	类型	说明
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	包含特定于 Azure OpenAI 模型终结点的参数。
kind	string: azureOpenAI	AI 模型的类型。

KnowledgeAgentModelKind

枚举

用于查询规划的 AI 模型。

值	说明
azureOpenAI	使用 Azure Open AI 模型进行查询规划。

KnowledgeAgentRequestLimits

Object

防护机制来限制单个代理检索请求使用的资源量。

名称	类型	说明
maxOutputSize	integer (int32)	限制输出中内容的最大大小。
maxRuntimeInSeconds	integer (int32)	最大运行时间（以秒为单位）。

KnowledgeAgentTargetIndex

Object

名称	类型	说明
defaultIncludeReferenceSourceData	boolean	指示是否应包含引用源数据。
defaultMaxDocsForReranker	integer (int32)	限制考虑进行排名的文档数量。
defaultRerankerThreshold	number (float) minimum: 0 maximum: 4	重新排名结果的阈值（范围：0-4）。
indexName	string	目标索引的名称。

OutputFieldMappingEntry

Object

技能的输出字段映射。

名称	类型	说明
name	string	技能定义的输出的名称。
targetName	string	输出的目标名称。它是可选的，默认为名称。

SearchIndexerDataNoneIdentity

Object

清除数据源的标识属性。

名称	类型	说明
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	指定标识类型的 URI 片段。

SearchIndexerDataUserAssignedIdentity

Object

指定要使用的数据源的标识。

名称	类型	说明
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	指定标识类型的 URI 片段。
userAssignedIdentity	string	用户分配的托管标识的完全限定的 Azure 资源 ID 通常以“/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentity/myId”的形式分配给搜索服务。

SearchResourceEncryptionKey

Object

Azure Key Vault 中的客户管理的加密密钥。创建和管理的密钥可用于加密或解密静态数据，例如索引和同义词映射。

名称	类型	说明
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`。

通过

Knowledge Agents - Create Or Update

URI 参数

请求头

请求正文

响应

示例

SearchServiceCreateOrUpdateKnowledgeAgent

示例请求

示例响应

定义

AzureActiveDirectoryApplicationCredentials

AzureOpenAIEmbeddingSkill

AzureOpenAIModelName

AzureOpenAIParameters

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

InputFieldMappingEntry

KnowledgeAgent

KnowledgeAgentAzureOpenAIModel

KnowledgeAgentModelKind

KnowledgeAgentRequestLimits

KnowledgeAgentTargetIndex

OutputFieldMappingEntry

SearchIndexerDataNoneIdentity

SearchIndexerDataUserAssignedIdentity

SearchResourceEncryptionKey