Knowledge Agents - Create

Serviço:: Search Service

Versão da API:: 2025-08-01-preview

Cria um novo agente.

POST {endpoint}/agents?api-version=2025-08-01-preview

Parâmetros de URI

Nome	Em	Obrigatório	Tipo	Description
endpoint	path	True	string	A URL do ponto de extremidade do serviço de pesquisa.
api-version	query	True	string	Versão da API do cliente.

Cabeçalho da solicitação

Nome	Obrigatório	Tipo	Description
x-ms-client-request-id		string (uuid)	O ID de rastreamento enviado com a solicitação para ajudar na depuração.

Corpo da solicitação

Nome	Obrigatório	Tipo	Description
knowledgeSources	True	KnowledgeSourceReference[]
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Contém opções de configuração sobre como se conectar a modelos de IA.
name	True	string	O nome do agente de conhecimento.
@odata.etag		string	A ETag do agente.
description		string	A descrição do agente.
encryptionKey		SearchResourceEncryptionKey	Uma descrição de uma chave de criptografia que você cria no Azure Key Vault. Essa chave é usada para fornecer um nível adicional de criptografia em repouso para a definição do agente quando você deseja garantia total de que ninguém, nem mesmo a Microsoft, pode descriptografá-los. Depois de criptografar sua definição de agente, ela sempre permanecerá criptografada. O serviço de pesquisa ignorará as tentativas de definir essa propriedade como nula. Você pode alterar essa propriedade conforme necessário se quiser girar sua chave de criptografia; Sua definição de agente não será afetada. A criptografia com chaves gerenciadas pelo cliente não está disponível para serviços de pesquisa gratuitos e só está disponível para serviços pagos criados a partir de 1º de janeiro de 2019.
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	Proteções para limitar a quantidade de recursos utilizados para uma solicitação de recuperação de agente único.
retrievalInstructions		string	Instruções consideradas pelo agente de conhecimento ao desenvolver o plano de consulta.

Respostas

Nome	Tipo	Description
201 Created	KnowledgeAgent	Criou um agente com sucesso
Other Status Codes	ErrorResponse	Resposta de erro.

Exemplos

SearchServiceCreateKnowledgeAgent

Solicitação de exemplo

HTTP

POST https://previewexampleservice.search.windows.net/agents?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-4.1-nano"
      },
      "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."
}

Resposta de exemplo

Código de status:: 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-4.1-nano"
      }
    }
  ],
  "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>"
    }
  }
}

Definições

Nome	Description
AzureActiveDirectoryApplicationCredentials	Credenciais de um aplicativo registrado criado para o serviço de pesquisa, usado para acesso autenticado às chaves de criptografia armazenadas no Azure Key Vault.
AzureOpenAIEmbeddingSkill	Permite gerar uma inserção de vetor para uma determinada entrada de texto usando o recurso OpenAI do Azure.
AzureOpenAIModelName	O nome do modelo do Azure Open AI que será chamado.
AzureOpenAIParameters	Especifica os parâmetros para se conectar ao recurso OpenAI do Azure.
ErrorAdditionalInfo	As informações adicionais do erro de gerenciamento de recursos.
ErrorDetail	O detalhe do erro.
ErrorResponse	Resposta de erro
InputFieldMappingEntry	Mapeamento de campo de entrada para uma habilidade.
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	Especifica o recurso OpenAI do Azure usado para fazer o planejamento de consulta.
KnowledgeAgentModelKind	O modelo de IA a ser usado para planejamento de consulta.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	A configuração de saída para o agente
KnowledgeAgentRequestLimits	Proteções para limitar a quantidade de recursos utilizados para uma solicitação de recuperação de agente único.
KnowledgeSourceReference
OutputFieldMappingEntry	Mapeamento de campo de saída para uma habilidade.
SearchIndexerDataNoneIdentity	Limpa a propriedade de identidade de uma fonte de dados.
SearchIndexerDataUserAssignedIdentity	Especifica a identidade de uma fonte de dados a ser usada.
SearchResourceEncryptionKey	Uma chave de criptografia gerenciada pelo cliente no Azure Key Vault. As chaves que você cria e gerencia podem ser usadas para criptografar ou descriptografar dados em repouso, como índices e mapas de sinônimos.

AzureActiveDirectoryApplicationCredentials

Objeto

Credenciais de um aplicativo registrado criado para o serviço de pesquisa, usado para acesso autenticado às chaves de criptografia armazenadas no Azure Key Vault.

Nome	Tipo	Description
applicationId	string	Uma ID de Aplicativo do AAD que recebeu as permissões de acesso necessárias ao Azure Key Vault que deve ser usado ao criptografar seus dados em repouso. A ID do Aplicativo não deve ser confundida com a ID do Objeto do Aplicativo AAD.
applicationSecret	string	A chave de autenticação do aplicativo AAD especificado.

AzureOpenAIEmbeddingSkill

Objeto

Permite gerar uma inserção de vetor para uma determinada entrada de texto usando o recurso OpenAI do Azure.

Nome	Tipo	Description
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Um fragmento de URI especificando o tipo de habilidade.
apiKey	string	Chave de API do recurso OpenAI do Azure designado.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	A identidade gerenciada atribuída pelo usuário usada para conexões de saída.
context	string	Representa o nível em que as operações ocorrem, como a raiz do documento ou o conteúdo do documento (por exemplo, /document ou /document/content). O padrão é /document.
deploymentId	string	ID da implantação do modelo OpenAI do Azure no recurso designado.
description	string	A descrição da habilidade que descreve as entradas, saídas e uso da habilidade.
dimensions	integer (int32)	O número de dimensões que as inserções de saída resultantes devem ter. Compatível apenas com text-embedding-3 e modelos posteriores.
inputs	InputFieldMappingEntry[]	As entradas das habilidades podem ser uma coluna no conjunto de dados de origem ou a saída de uma habilidade upstream.
modelName	AzureOpenAIModelName	O nome do modelo de inserção implantado no caminho deploymentId fornecido.
name	string	O nome da habilidade que a identifica exclusivamente no conjunto de habilidades. Uma habilidade sem nome definido receberá um nome padrão de seu índice baseado em 1 na matriz de habilidades, prefixado com o caractere '#'.
outputs	OutputFieldMappingEntry[]	A saída de uma habilidade é um campo em um índice de pesquisa ou um valor que pode ser consumido como uma entrada por outra habilidade.
resourceUri	string (uri)	O URI do recurso OpenAI do Azure.

AzureOpenAIModelName

Enumeração

O nome do modelo do Azure Open AI que será chamado.

Valor	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

Objeto

Especifica os parâmetros para se conectar ao recurso OpenAI do Azure.

Nome	Tipo	Description
apiKey	string	Chave de API do recurso OpenAI do Azure designado.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	A identidade gerenciada atribuída pelo usuário usada para conexões de saída.
deploymentId	string	ID da implantação do modelo OpenAI do Azure no recurso designado.
modelName	AzureOpenAIModelName	O nome do modelo de inserção implantado no caminho deploymentId fornecido.
resourceUri	string (uri)	O URI do recurso OpenAI do Azure.

ErrorAdditionalInfo

Objeto

As informações adicionais do erro de gerenciamento de recursos.

Nome	Tipo	Description
info	object	As informações adicionais.
type	string	O tipo de informação adicional.

ErrorDetail

Objeto

O detalhe do erro.

Nome	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	As informações adicionais do erro.
code	string	O código do erro.
details	ErrorDetail[]	Os detalhes do erro.
message	string	A mensagem de erro.
target	string	O destino do erro.

ErrorResponse

Objeto

Resposta de erro

Nome	Tipo	Description
error	ErrorDetail	O objeto de erro.

InputFieldMappingEntry

Objeto

Mapeamento de campo de entrada para uma habilidade.

Nome	Tipo	Description
inputs	InputFieldMappingEntry[]	As entradas recursivas usadas ao criar um tipo complexo.
name	string	O nome da entrada.
source	string	A origem da entrada.
sourceContext	string	O contexto de origem usado para selecionar entradas recursivas.

KnowledgeAgent

Objeto

Nome	Tipo	Description
@odata.etag	string	A ETag do agente.
description	string	A descrição do agente.
encryptionKey	SearchResourceEncryptionKey	Uma descrição de uma chave de criptografia que você cria no Azure Key Vault. Essa chave é usada para fornecer um nível adicional de criptografia em repouso para a definição do agente quando você deseja garantia total de que ninguém, nem mesmo a Microsoft, pode descriptografá-los. Depois de criptografar sua definição de agente, ela sempre permanecerá criptografada. O serviço de pesquisa ignorará as tentativas de definir essa propriedade como nula. Você pode alterar essa propriedade conforme necessário se quiser girar sua chave de criptografia; Sua definição de agente não será afetada. A criptografia com chaves gerenciadas pelo cliente não está disponível para serviços de pesquisa gratuitos e só está disponível para serviços pagos criados a partir de 1º de janeiro de 2019.
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Contém opções de configuração sobre como se conectar a modelos de IA.
name	string	O nome do agente de conhecimento.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Proteções para limitar a quantidade de recursos utilizados para uma solicitação de recuperação de agente único.
retrievalInstructions	string	Instruções consideradas pelo agente de conhecimento ao desenvolver o plano de consulta.

KnowledgeAgentAzureOpenAIModel

Objeto

Especifica o recurso OpenAI do Azure usado para fazer o planejamento de consulta.

Nome	Tipo	Description
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Contém os parâmetros específicos do ponto de extremidade do modelo OpenAI do Azure.
kind	string: azureOpenAI	O tipo de modelo de IA.

KnowledgeAgentModelKind

Enumeração

O modelo de IA a ser usado para planejamento de consulta.

Valor	Description
azureOpenAI	Use modelos de IA aberta do Azure para planejamento de consulta.

KnowledgeAgentOutputConfiguration

Objeto

Nome	Tipo	Description
answerInstructions	string	Instruções consideradas pelo agente de conhecimento ao gerar respostas
attemptFastPath	boolean	Indica se o agente deve tentar emitir a mensagem de chat mais recente como uma consulta direta às fontes de conhecimento, ignorando as chamadas de modelo.
includeActivity	boolean	Indica que os resultados da recuperação devem incluir informações sobre a atividade.
modality	KnowledgeAgentOutputConfigurationModality	A configuração de saída para o agente

KnowledgeAgentOutputConfigurationModality

Enumeração

A configuração de saída para o agente

Valor	Description
answerSynthesis	Sintetize uma resposta para a carga de resposta.
extractiveData	Retorne dados das fontes de conhecimento diretamente sem alteração geradora.

KnowledgeAgentRequestLimits

Objeto

Proteções para limitar a quantidade de recursos utilizados para uma solicitação de recuperação de agente único.

Nome	Tipo	Description
maxOutputSize	integer (int32)	Limita o tamanho máximo do conteúdo na saída.
maxRuntimeInSeconds	integer (int32)	O tempo máximo de execução em segundos.

KnowledgeSourceReference

Objeto

Nome	Tipo	Description
alwaysQuerySource	boolean	Indica que essa fonte de conhecimento deve ignorar a seleção da fonte e sempre ser consultada no momento da recuperação.
includeReferenceSourceData	boolean	Indica se as referências devem incluir os dados estruturados obtidos durante a recuperação em sua carga.
includeReferences	boolean	Indica se as referências devem ser incluídas para dados recuperados dessa fonte.
maxSubQueries	integer (int32)	O número máximo de consultas que podem ser emitidas por vez ao recuperar dados dessa fonte.
name	string	O nome da fonte de conhecimento.
rerankerThreshold	number (float)	O limite de reclassificação que todos os documentos recuperados devem atender para serem incluídos na resposta.

OutputFieldMappingEntry

Objeto

Mapeamento de campo de saída para uma habilidade.

Nome	Tipo	Description
name	string	O nome da saída definida pela habilidade.
targetName	string	O nome de destino da saída. É opcional e o nome é padrão.

SearchIndexerDataNoneIdentity

Objeto

Limpa a propriedade de identidade de uma fonte de dados.

Nome	Tipo	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Um fragmento de URI especificando o tipo de identidade.

SearchIndexerDataUserAssignedIdentity

Objeto

Especifica a identidade de uma fonte de dados a ser usada.

Nome	Tipo	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Um fragmento de URI especificando o tipo de identidade.
userAssignedIdentity	string	A ID de recurso do Azure totalmente qualificada de uma identidade gerenciada atribuída pelo usuário, normalmente no formato "/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" que deveria ter sido atribuída ao serviço de pesquisa.

SearchResourceEncryptionKey

Objeto

Uma chave de criptografia gerenciada pelo cliente no Azure Key Vault. As chaves que você cria e gerencia podem ser usadas para criptografar ou descriptografar dados em repouso, como índices e mapas de sinônimos.

Nome	Tipo	Description
accessCredentials	AzureActiveDirectoryApplicationCredentials	Credenciais opcionais do Azure Active Directory usadas para acessar o Azure Key Vault. Não é necessário se estiver usando a identidade gerenciada.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Uma identidade gerenciada explícita a ser usada para essa chave de criptografia. Se não for especificado e a propriedade de credenciais de acesso for nula, a identidade gerenciada atribuída pelo sistema será usada. Na atualização do recurso, se a identidade explícita não for especificada, ela permanecerá inalterada. Se "none" for especificado, o valor dessa propriedade será limpo.
keyVaultKeyName	string	O nome da chave do Azure Key Vault a ser usada para criptografar seus dados em repouso.
keyVaultKeyVersion	string	A versão da chave do Azure Key Vault a ser usada para criptografar seus dados em repouso.
keyVaultUri	string	O URI do Azure Key Vault, também conhecido como nome DNS, que contém a chave a ser usada para criptografar seus dados em repouso. Um exemplo de URI pode ser `https://my-keyvault-name.vault.azure.net`.