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

Knowledge Agents - Create Or Update

服务:: Search Service

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

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

PUT {endpoint}/agents('{agentName}')?api-version=2025-08-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 请求，指示服务在成功时返回创建/更新的资源。

请求正文

名称	必需	类型	说明
knowledgeSources	True	KnowledgeSourceReference[]
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	包含有关如何连接到 AI 模型的配置选项。
name	True	string	知识代理的名称。
@odata.etag		string	代理的 ETag。
description		string	代理的说明。
encryptionKey		SearchResourceEncryptionKey	在 Azure Key Vault 中创建的加密密钥的说明。当你希望完全保证没有人（甚至 Microsoft）无法解密它们时，此密钥用于为代理定义提供额外的静态加密级别。加密代理定义后，它将始终保持加密状态。搜索服务将忽略将此属性设置为 null 的尝试。如果要轮换加密密钥，可以根据需要更改此属性;您的代理定义将不受影响。使用客户管理的密钥进行加密不适用于免费搜索服务，仅适用于 2019 年 1 月 1 日或之后创建的付费服务。
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	用于限制单个代理检索请求使用的资源量的护栏。
retrievalInstructions		string	知识代理在开发查询计划时考虑的指令。

响应

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

定义

名称	说明
AzureActiveDirectoryApplicationCredentials	为搜索服务创建的已注册应用程序的凭据，用于对存储在 Azure Key Vault 中的加密密钥进行身份验证访问。
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 Key Vault 中的加密密钥进行身份验证访问。

名称	类型	说明
applicationId	string	向 Azure Key Vault 授予所需的访问权限的 AAD 应用程序 ID，该权限将在加密静态数据时使用。应用程序 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)	生成的输出嵌入应有的维度数。仅在 text-embedding-3 及更高版本中受支持。
inputs	InputFieldMappingEntry[]	技能的输入可以是源数据集中的列，也可以是上游技能的输出。
modelName	AzureOpenAIModelName	部署在提供的 deploymentId 路径上的嵌入模型的名称。
name	string	在技能集中唯一标识它的技能的名称。未定义名称的技能将在技能数组中为其从 1 开始的索引的默认名称，前缀为字符“#”。
outputs	OutputFieldMappingEntry[]	技能的输出要么是搜索索引中的字段，要么是可作为其他技能输入使用的值。
resourceUri	string (uri)	Azure OpenAI 资源的资源 URI。

AzureOpenAIModelName

枚举

将调用的 Azure Open AI 模型名称。

值	说明
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 资源的参数。

名称	类型	说明
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 日或之后创建的付费服务。
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	包含有关如何连接到 AI 模型的配置选项。
name	string	知识代理的名称。
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	用于限制单个代理检索请求使用的资源量的护栏。
retrievalInstructions	string	知识代理在开发查询计划时考虑的指令。

KnowledgeAgentAzureOpenAIModel

Object

指定用于执行查询规划的 Azure OpenAI 资源。

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

KnowledgeAgentModelKind

枚举

用于查询规划的 AI 模型。

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

KnowledgeAgentOutputConfiguration

Object

名称	类型	说明
answerInstructions	string	知识代理在生成答案时考虑的指令
attemptFastPath	boolean	指示代理是否应尝试绕过模型调用，将最新的聊天消息作为对知识源的直接查询。
includeActivity	boolean	指示检索结果应包括活动信息。
modality	KnowledgeAgentOutputConfigurationModality	代理的输出配置

KnowledgeAgentOutputConfigurationModality

枚举

代理的输出配置

值	说明
answerSynthesis	合成响应有效负载的答案。
extractiveData	直接从知识源返回数据，无需生成更改。

KnowledgeAgentRequestLimits

Object

用于限制单个代理检索请求使用的资源量的护栏。

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

KnowledgeSourceReference

Object

名称	类型	说明
alwaysQuerySource	boolean	指示此知识源应绕过源选择，并始终在检索时进行查询。
includeReferenceSourceData	boolean	指示引用是否应在其有效负载中包含检索期间获得的结构化数据。
includeReferences	boolean	指示是否应为从此源检索的数据包含引用。
maxSubQueries	integer (int32)	从此源检索数据时一次可以发出的最大查询数。
name	string	知识源的名称。
rerankerThreshold	number (float)	所有检索到的文档必须满足重新排序器阈值才能包含在响应中。

OutputFieldMappingEntry

Object

技能的输出字段映射。

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

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-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/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 密钥保管库的 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

KnowledgeAgentOutputConfiguration

KnowledgeAgentOutputConfigurationModality

KnowledgeAgentRequestLimits

KnowledgeSourceReference

OutputFieldMappingEntry

SearchIndexerDataNoneIdentity

SearchIndexerDataUserAssignedIdentity

SearchResourceEncryptionKey