Knowledge Agents - Get

Serviço:: Search Service

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

Recupera uma definição de agente.

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

Parâmetros URI

Nome	Em	Necessário	Tipo	Descrição
agentName	path	True	string	O nome do agente a ser recuperado.
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 de Pedido

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

Respostas

Nome	Tipo	Descrição
200 OK	KnowledgeAgent
Other Status Codes	ErrorResponse	Resposta de erro.

Exemplos

SearchServiceGetKnowledgeAgent

Pedido de exemplo

HTTP

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

Resposta de exemplo

Código de estado:: 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>"
    }
  }
}

Definições

Nome	Descrição
AzureActiveDirectoryApplicationCredentials	Credenciais de um aplicativo registrado criado para seu serviço de pesquisa, usado para acesso autenticado às chaves de criptografia armazenadas no Cofre de Chaves do Azure.
AzureOpenAIEmbeddingSkill	Permite gerar uma incorporação vetorial para uma determinada entrada de texto usando o recurso Azure OpenAI.
AzureOpenAIModelName	O nome do modelo de IA aberta do Azure que será chamado.
AzureOpenAIParameters	Especifica os parâmetros para se conectar ao recurso OpenAI do Azure.
ErrorAdditionalInfo	O erro de gerenciamento de recursos informações adicionais.
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 consultas.
KnowledgeAgentModelKind	O modelo de IA a ser usado para o planejamento de consultas.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	A configuração de saída para o agente
KnowledgeAgentRequestLimits	Guardrails para limitar a quantidade de recursos utilizados para uma solicitação de recuperação de um único agente.
KnowledgeSourceReference
OutputFieldMappingEntry	Mapeamento de campo de saída para uma habilidade.
SearchIndexerDataNoneIdentity	Limpa a propriedade identity de uma fonte de dados.
SearchIndexerDataUserAssignedIdentity	Especifica a identidade a ser usada por uma fonte de dados.
SearchResourceEncryptionKey	Uma chave de criptografia gerenciada pelo cliente no Cofre de Chaves do Azure. 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

Objetivo

Credenciais de um aplicativo registrado criado para seu serviço de pesquisa, usado para acesso autenticado às chaves de criptografia armazenadas no Cofre de Chaves do Azure.

Nome	Tipo	Descrição
applicationId	string	Uma ID de Aplicativo AAD que recebeu as permissões de acesso necessárias ao Cofre da Chave do Azure que deve ser usada ao criptografar seus dados em repouso. A ID do aplicativo não deve ser confundida com a ID do objeto do seu aplicativo AAD.
applicationSecret	string	A chave de autenticação do aplicativo AAD especificado.

AzureOpenAIEmbeddingSkill

Objetivo

Permite gerar uma incorporação vetorial para uma determinada entrada de texto usando o recurso Azure OpenAI.

Nome	Tipo	Descrição
@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 no qual 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 incorporações de saída resultantes devem ter. Suportado apenas em 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 a montante.
modelName	AzureOpenAIModelName	O nome do modelo de incorporação implantado no caminho deploymentId fornecido.
name	string	O nome da habilidade que a identifica exclusivamente dentro do conjunto de habilidades. Uma habilidade sem nome definido receberá um nome padrão de seu índice baseado em 1 na matriz de habilidades, prefixada 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 Azure OpenAI.

AzureOpenAIModelName

Enumeração

O nome do modelo de IA aberta do Azure que será chamado.

Valor	Descrição
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

Objetivo

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

Nome	Tipo	Descrição
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 incorporação implantado no caminho deploymentId fornecido.
resourceUri	string (uri)	O URI do recurso Azure OpenAI.

ErrorAdditionalInfo

Objetivo

O erro de gerenciamento de recursos informações adicionais.

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

ErrorDetail

Objetivo

O detalhe do erro.

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

ErrorResponse

Objetivo

Resposta de erro

Nome	Tipo	Descrição
error	ErrorDetail	O objeto de erro.

InputFieldMappingEntry

Objetivo

Mapeamento de campo de entrada para uma habilidade.

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

KnowledgeAgent

Objetivo

Nome	Tipo	Descrição
@odata.etag	string	O ETag do agente.
description	string	A descrição do agente.
encryptionKey	SearchResourceEncryptionKey	Uma descrição de uma chave de criptografia que você cria no Cofre de Chaves do Azure. Essa chave é usada para fornecer um nível adicional de criptografia em repouso para sua definição de agente quando você quiser garantia total de que ninguém, nem mesmo a Microsoft, pode descriptografá-los. Depois de ter criptografado sua definição de agente, ela sempre permanecerá criptografada. O serviço de pesquisa ignorará as tentativas de definir essa propriedade como null. 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 em ou após 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	Guardrails para limitar a quantidade de recursos utilizados para uma solicitação de recuperação de um único agente.
retrievalInstructions	string	Instruções consideradas pelo agente de conhecimento ao desenvolver o plano de consulta.

KnowledgeAgentAzureOpenAIModel

Objetivo

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

Nome	Tipo	Descrição
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Contém os parâmetros específicos para o 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 o planejamento de consultas.

Valor	Descrição
azureOpenAI	Use modelos de IA aberta do Azure para planejamento de consultas.

KnowledgeAgentOutputConfiguration

Objetivo

Nome	Tipo	Descrição
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	Descrição
answerSynthesis	Sintetize uma resposta para a carga útil de resposta.
extractiveData	Retornar dados das fontes de conhecimento diretamente, sem alteração generativa.

KnowledgeAgentRequestLimits

Objetivo

Guardrails para limitar a quantidade de recursos utilizados para uma solicitação de recuperação de um único agente.

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

KnowledgeSourceReference

Objetivo

Nome	Tipo	Descrição
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 útil.
includeReferences	boolean	Indica se devem ser incluídas referências para os dados recuperados dessa fonte.
maxSubQueries	integer (int32)	O número máximo de consultas que podem ser emitidas de cada 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 cumprir para serem incluídos na resposta.

OutputFieldMappingEntry

Objetivo

Mapeamento de campo de saída para uma habilidade.

Nome	Tipo	Descrição
name	string	O nome da saída definida pela habilidade.
targetName	string	O nome de destino da saída. É opcional e padrão para nomear.

SearchIndexerDataNoneIdentity

Objetivo

Limpa a propriedade identity de uma fonte de dados.

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

SearchIndexerDataUserAssignedIdentity

Objetivo

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

Nome	Tipo	Descrição
@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 ao usuário normalmente no formato "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" que deveria ter sido atribuída ao serviço de pesquisa.

SearchResourceEncryptionKey

Objetivo

Uma chave de criptografia gerenciada pelo cliente no Cofre de Chaves do Azure. 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	Descrição
accessCredentials	AzureActiveDirectoryApplicationCredentials	Credenciais opcionais do Azure Ative Directory usadas para acessar seu Cofre da Chave do Azure. 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 ao sistema será usada. Na atualização do recurso, se a identidade explícita não for especificada, ela permanecerá inalterada. Se "nenhum" for especificado, o valor dessa propriedade será limpo.
keyVaultKeyName	string	O nome da sua chave do Cofre da Chave do Azure a ser usada para criptografar seus dados em repouso.
keyVaultKeyVersion	string	A versão da chave do Cofre da Chave do Azure a ser usada para criptografar seus dados em repouso.
keyVaultUri	string	O URI do seu Cofre da Chave do Azure, 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`.