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)	Идентификатор отслеживания, отправляемый запросом на отладку.
If-Match		string	Определяет условие If-Match. Операция будет выполнена только в том случае, если ETag на сервере соответствует этому значению.
If-None-Match		string	Определяет условие If-None-Match. Операция будет выполнена только в том случае, если ETag на сервере не соответствует этому значению.
Prefer	True	string	Для HTTP-запросов PUT служба возвращает созданный или обновленный ресурс успешно.

Текст запроса

Имя	Обязательно	Тип	Описание
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Содержит параметры конфигурации для подключения к моделям ИИ.
name	True	string	Имя агента знаний.
targetIndexes	True	KnowledgeAgentTargetIndex[]
@odata.etag		string	ETag агента.
description		string	Описание агента.
encryptionKey		SearchResourceEncryptionKey	Описание ключа шифрования, созданного в Azure Key Vault. Этот ключ используется для обеспечения дополнительного уровня шифрования при хранении для определения агента, когда требуется полная уверенность в том, что никто, даже корпорация Майкрософт, не сможет его расшифровать. После шифрования определения агента оно всегда будет оставаться зашифрованным. Служба поиска игнорирует попытки задать для этого свойства значение NULL. Вы можете изменить это свойство по мере необходимости, если хотите повернуть ключ шифрования; Определение вашего агента не будет затронуто. Шифрование с помощью ключей, управляемых клиентом, недоступно для бесплатных служб поиска и доступно только для платных служб, созданных 1 января 2019 г.
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	Модель ИИ, которая будет использоваться для планирования запросов.
KnowledgeAgentRequestLimits	Защитные ограждения для ограничения объема ресурсов, используемых для запроса на получение данных одним агентом.
KnowledgeAgentTargetIndex
OutputFieldMappingEntry	Сопоставление полей вывода для навыка.
SearchIndexerDataNoneIdentity	Очищает свойство удостоверения источника данных.
SearchIndexerDataUserAssignedIdentity	Указывает удостоверение для используемого источника данных.
SearchResourceEncryptionKey	Ключ шифрования, управляемый клиентом, в Azure Key Vault. Ключи, которые создаются и управляются, можно использовать для шифрования или расшифровки неактивных данных, таких как индексы и карты синонимов.

AzureActiveDirectoryApplicationCredentials

Object

Учетные данные зарегистрированного приложения, созданного для службы поиска, используемого для проверки подлинности доступа к ключам шифрования, хранящимся в Azure Key Vault.

Имя	Тип	Описание
applicationId	string	Идентификатор приложения AAD, которому было предоставлено необходимые разрешения на доступ к Azure Key Vault, который будет использоваться при шифровании неактивных данных. Идентификатор приложения не следует путать с идентификатором объекта для приложения AAD.
applicationSecret	string	Ключ проверки подлинности указанного приложения AAD.

AzureOpenAIEmbeddingSkill

Object

Позволяет создать вектор внедрения для заданного текстового ввода с помощью ресурса Azure OpenAI.

Имя	Тип	Описание
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Фрагмент URI, указывающий тип навыка.
apiKey	string	Ключ API указанного ресурса Azure OpenAI.
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)	URI ресурса ресурса Azure OpenAI.

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	Ключ API указанного ресурса Azure OpenAI.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Назначаемое пользователем управляемое удостоверение, используемое для исходящих подключений.
deploymentId	string	Идентификатор развертывания модели Azure OpenAI в указанном ресурсе.
modelName	AzureOpenAIModelName	Имя модели внедрения, развернутой по указанному пути deploymentId.
resourceUri	string (uri)	URI ресурса ресурса Azure OpenAI.

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. Этот ключ используется для обеспечения дополнительного уровня шифрования при хранении для определения агента, когда требуется полная уверенность в том, что никто, даже корпорация Майкрософт, не сможет его расшифровать. После шифрования определения агента оно всегда будет оставаться зашифрованным. Служба поиска игнорирует попытки задать для этого свойства значение NULL. Вы можете изменить это свойство по мере необходимости, если хотите повернуть ключ шифрования; Определение вашего агента не будет затронуто. Шифрование с помощью ключей, управляемых клиентом, недоступно для бесплатных служб поиска и доступно только для платных служб, созданных 1 января 2019 г.
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Содержит параметры конфигурации для подключения к моделям ИИ.
name	string	Имя агента знаний.
requestLimits	KnowledgeAgentRequestLimits	Защитные ограждения для ограничения объема ресурсов, используемых для запроса на получение данных одним агентом.
targetIndexes	KnowledgeAgentTargetIndex[]

KnowledgeAgentAzureOpenAIModel

Object

Указывает ресурс Azure OpenAI, используемый для планирования запросов.

Имя	Тип	Описание
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Содержит параметры, относящиеся к конечной точке модели Azure OpenAI.
kind	string: azureOpenAI	Тип модели ИИ.

KnowledgeAgentModelKind

Перечисление

Модель ИИ, которая будет использоваться для планирования запросов.

Значение	Описание
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 назначаемого пользователем управляемого удостоверения обычно в форме "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId", который должен быть назначен службе поиска.

SearchResourceEncryptionKey

Object

Ключ шифрования, управляемый клиентом, в Azure Key Vault. Ключи, которые создаются и управляются, можно использовать для шифрования или расшифровки неактивных данных, таких как индексы и карты синонимов.

Имя	Тип	Описание
accessCredentials	AzureActiveDirectoryApplicationCredentials	Необязательные учетные данные Azure Active Directory, используемые для доступа к Azure Key Vault. Не требуется, если вместо этого используется управляемое удостоверение.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Явное управляемое удостоверение, используемое для этого ключа шифрования. Если не указано, а свойство учетных данных доступа равно NULL, используется управляемое удостоверение, назначаемое системой. При обновлении ресурса, если явное удостоверение не указано, оно остается неизменным. Если задано значение none, то значение этого свойства очищается.
keyVaultKeyName	string	Имя ключа Azure Key Vault, используемого для шифрования неактивных данных.
keyVaultKeyVersion	string	Версия ключа Azure Key Vault, используемая для шифрования неактивных данных.
keyVaultUri	string	Универсальный код ресурса (URI) Хранилища ключей Azure, который также называется 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