Knowledge Agents - Get

Serviço:: Search Service

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

Recupera uma definição de agente.

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

Parâmetros de URI

Nome	Em	Obrigatório	Tipo	Description
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 da solicitação

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

Respostas

Nome	Tipo	Description
200 OK	KnowledgeAgent
Other Status Codes	ErrorResponse	Resposta de erro.

Exemplos

SearchServiceGetKnowledgeAgent

Solicitação de exemplo

HTTP

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

Resposta de exemplo

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

Definições

Nome	Description
AzureActiveDirectoryApplicationCredentials	Credenciais de um aplicativo registrado criado para seu serviço de pesquisa, usado para acesso autenticado às chaves de criptografia armazenadas no Azure Key Vault.
AzureOpenAIEmbeddingSkill	Permite que você gere uma inserção de vetor 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 do Azure OpenAI.
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.
KnowledgeAgentRequestLimits	Proteções para limitar a quantidade de recursos utilizados para uma solicitação de recuperação de agente único.
KnowledgeAgentTargetIndex
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 seu 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 para o Azure Key Vault que deve ser usada ao criptografar seus dados em repouso. A ID do aplicativo não deve ser confundida com a ID do objeto para seu aplicativo do AAD.
applicationSecret	string	A chave de autenticação do aplicativo AAD especificado.

AzureOpenAIEmbeddingSkill

Objeto

Permite que você gere uma inserção de vetor para uma determinada entrada de texto usando o recurso Azure OpenAI.

Nome	Tipo	Description
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Um fragmento de URI que especifica o tipo de habilidade.
apiKey	string	Chave de API do recurso Azure OpenAI 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 de modelo do Azure OpenAI no recurso designado.
description	string	A descrição da habilidade que descreve as entradas, as saídas e o uso da habilidade.
dimensions	integer (int32)	O número de dimensões que as inserções de saída resultantes devem ter. Só há suporte em modelos text-embedding-3 e 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 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, 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 entrada por outra habilidade.
resourceUri	string (uri)	O URI do recurso do Azure OpenAI.

AzureOpenAIModelName

Enumeração

O nome do modelo de IA Aberta do Azure 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 do Azure OpenAI.

Nome	Tipo	Description
apiKey	string	Chave de API do recurso Azure OpenAI 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 de modelo do Azure OpenAI no recurso designado.
modelName	AzureOpenAIModelName	O nome do modelo de inserção implantado no caminho deploymentId fornecido.
resourceUri	string (uri)	O URI do recurso do Azure OpenAI.

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 de 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 em 1º de janeiro de 2019 ou depois de 1º de janeiro de 2019.
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.
requestLimits	KnowledgeAgentRequestLimits	Proteções para limitar a quantidade de recursos utilizados para uma solicitação de recuperação de agente único.
targetIndexes	KnowledgeAgentTargetIndex[]

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.

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.

KnowledgeAgentTargetIndex

Objeto

Nome	Tipo	Description
defaultIncludeReferenceSourceData	boolean	Indica se os dados da fonte de referência devem ser incluídos.
defaultMaxDocsForReranker	integer (int32)	Limita o número de documentos considerados para classificação.
defaultRerankerThreshold	number (float) minimum: 0 maximum: 4	Um limite para reclassificação de resultados (intervalo: 0-4).
indexName	string	O nome do índice de destino.

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. Ele é opcional e o padrão para nomear.

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 que especifica 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 que especifica 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-12334-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. Ao atualizar para o 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 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 URI de exemplo pode ser `https://my-keyvault-name.vault.azure.net`.