Knowledge Agents - Get

Служба:: Search Service

Версия API:: 2025-08-01-preview

Извлекает определение агента.

GET {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)	Идентификатор отслеживания, отправленный вместе с запросом на помощь в отладке.

Ответы

Имя	Тип	Описание
200 OK	KnowledgeAgent
Other Status Codes	ErrorResponse	Ответ на ошибку.

Примеры

SearchServiceGetKnowledgeAgent

Образец запроса

HTTP

GET https://previewexampleservice.search.windows.net/agents('agent-preview-test')?api-version=2025-08-01-preview

Пример ответа

Код состояния:: 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": "<redacted>",
        "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	Модель ИИ, которая будет использоваться для планирования запросов.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	Конфигурация вывода для агента
KnowledgeAgentRequestLimits	Защитные ограждения для ограничения объема ресурсов, используемых для запроса на получение данных одним агентом.
KnowledgeSourceReference
OutputFieldMappingEntry	Сопоставление выходных полей для навыка.
SearchIndexerDataNoneIdentity	Очищает свойство identity источника данных.
SearchIndexerDataUserAssignedIdentity	Указывает идентификатор для используемого источника данных.
SearchResourceEncryptionKey	Ключ шифрования, управляемый клиентом, в Azure Key Vault. Ключи, которые вы создаете и которыми управляете, можно использовать для шифрования или расшифровки хранимых данных, таких как индексы и сопоставления синонимов.

AzureActiveDirectoryApplicationCredentials

Объект

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

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

AzureOpenAIEmbeddingSkill

Объект

Позволяет создать векторное встраивание для заданного текстового ввода с помощью ресурса 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)	Число измерений, в которых должны быть внедренные выходные данные. Поддерживается только в моделях text-embedding-3 и более поздних версий.
inputs	InputFieldMappingEntry[]	Входными данными навыков может быть столбец в исходном наборе данных или выходные данные вышестоящего навыка.
modelName	AzureOpenAIModelName	Имя модели внедрения, которая развертывается по указанному пути deploymentId.
name	string	Название навыка, которое однозначно идентифицирует его в наборе навыков. Навыку, имя которого не определено, будет присвоено по умолчанию в виде индекса из 1 в массиве навыков, начинающегося с префикса '#'.
outputs	OutputFieldMappingEntry[]	Выходными данными навыка является либо поле в индексе поиска, либо значение, которое может быть использовано в качестве входных данных другим навыком.
resourceUri	string (uri)	URI ресурса Azure OpenAI.

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

Объект

Указывает параметры для подключения к ресурсу 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

Объект

Дополнительные сведения об ошибке управления ресурсами.

Имя	Тип	Описание
info	object	Дополнительные сведения.
type	string	Дополнительный тип сведений.

ErrorDetail

Объект

Сведения об ошибке.

Имя	Тип	Описание
additionalInfo	ErrorAdditionalInfo[]	Дополнительные сведения об ошибке.
code	string	Код ошибки.
details	ErrorDetail[]	Сведения об ошибке.
message	string	Сообщение об ошибке.
target	string	Целевой объект ошибки.

ErrorResponse

Объект

Ответ на ошибку

Имя	Тип	Описание
error	ErrorDetail	Объект ошибки.

InputFieldMappingEntry

Объект

Сопоставление полей ввода для навыка.

Имя	Тип	Описание
inputs	InputFieldMappingEntry[]	Рекурсивные входные данные, используемые при создании сложного типа.
name	string	Имя входных данных.
source	string	Источник входных данных.
sourceContext	string	Исходный контекст, используемый для выбора рекурсивных входных данных.

KnowledgeAgent

Объект

Имя	Тип	Описание
@odata.etag	string	ETag агента.
description	string	Описание агента.
encryptionKey	SearchResourceEncryptionKey	Описание ключа шифрования, созданного в Azure Key Vault. Этот ключ используется для обеспечения дополнительного уровня шифрования при хранении для определения агента, когда требуется полная уверенность в том, что никто, даже корпорация Майкрософт, не сможет его расшифровать. После шифрования определения агента оно всегда будет оставаться зашифрованным. Служба поиска будет игнорировать попытки установить для этого свойства значение null. Вы можете изменить это свойство по мере необходимости, если хотите повернуть ключ шифрования; Определение вашего агента не будет затронуто. Шифрование с помощью ключей, управляемых клиентом, недоступно для бесплатных поисковых служб и доступно только для платных служб, созданных 1 января 2019 г. или позже.
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Содержит параметры конфигурации для подключения к моделям ИИ.
name	string	Имя агента знаний.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Защитные ограждения для ограничения объема ресурсов, используемых для запроса на получение данных одним агентом.
retrievalInstructions	string	Инструкции, учитываемые агентом базы знаний при разработке плана запроса.

KnowledgeAgentAzureOpenAIModel

Объект

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

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

KnowledgeAgentModelKind

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

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

Значение	Описание
azureOpenAI	Используйте модели Azure Open AI для планирования запросов.

KnowledgeAgentOutputConfiguration

Объект

Имя	Тип	Описание
answerInstructions	string	Инструкции, учитываемые агентом знаний при формировании ответов
attemptFastPath	boolean	Указывает, должен ли агент пытаться выдать самое последнее сообщение чата в виде прямого запроса к источникам знаний, минуя вызовы модели.
includeActivity	boolean	Указывает, что результаты извлечения должны содержать информацию о действиях.
modality	KnowledgeAgentOutputConfigurationModality	Конфигурация вывода для агента

KnowledgeAgentOutputConfigurationModality

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

Конфигурация вывода для агента

Значение	Описание
answerSynthesis	Синтезируйте ответ для полезной нагрузки ответа.
extractiveData	Возвращайте данные из источников знаний напрямую без генеративного изменения.

KnowledgeAgentRequestLimits

Объект

Защитные ограждения для ограничения объема ресурсов, используемых для запроса на получение данных одним агентом.

Имя	Тип	Описание
maxOutputSize	integer (int32)	Ограничивает максимальный размер содержимого на выходе.
maxRuntimeInSeconds	integer (int32)	Максимальное время работы в секундах.

KnowledgeSourceReference

Объект

Имя	Тип	Описание
alwaysQuerySource	boolean	Указывает, что этот источник знаний должен обходить выбор источника и всегда запрашиваться во время извлечения.
includeReferenceSourceData	boolean	Указывает, должны ли ссылки включать структурированные данные, полученные во время извлечения, в свои полезные данные.
includeReferences	boolean	Указывает, следует ли включать ссылки для данных, полученных из этого источника.
maxSubQueries	integer (int32)	Максимальное количество запросов, которое может быть выполнено за один раз при получении данных из этого источника.
name	string	Название источника знаний.
rerankerThreshold	number (float)	Пороговое значение для повторного ранжирования, которому должны соответствовать все извлеченные документы, чтобы быть включенным в ответ.

OutputFieldMappingEntry

Объект

Сопоставление выходных полей для навыка.

Имя	Тип	Описание
name	string	Имя выходных данных, определяемое навыком.
targetName	string	Целевое имя выходных данных. Он является необязательным и по умолчанию является именем.

SearchIndexerDataNoneIdentity

Объект

Очищает свойство identity источника данных.

Имя	Тип	Описание
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Фрагмент URI, указывающий тип удостоверения.

SearchIndexerDataUserAssignedIdentity

Объект

Указывает идентификатор для используемого источника данных.

Имя	Тип	Описание
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Фрагмент URI, указывающий тип удостоверения.
userAssignedIdentity	string	Полный идентификатор ресурса Azure управляемого удостоверения, назначенного пользователем, обычно в форме "/subscriptions/12345678-1234-1234-123467890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId", который должен быть назначен службе поиска.

SearchResourceEncryptionKey

Объект

Ключ шифрования, управляемый клиентом, в 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 Key Vault, также называемый DNS-именем, который содержит ключ, используемый для шифрования неактивных данных. Примером URI может быть .`https://my-keyvault-name.vault.azure.net`