Knowledge Agents - List

Servizio:: Search Service

Versione API:: 2025-08-01-preview

Elenca tutti gli agenti disponibili per un servizio di ricerca.

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

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
endpoint	path	True	string	URL dell'endpoint del servizio di ricerca.
api-version	query	True	string	Versione dell'API client.

Intestazione della richiesta

Nome	Necessario	Tipo	Descrizione
x-ms-client-request-id		string (uuid)	ID di rilevamento inviato con la richiesta di assistenza per il debug.

Risposte

Nome	Tipo	Descrizione
200 OK	ListKnowledgeAgentsResult
Other Status Codes	ErrorResponse	Risposta di errore.

Esempio

SearchServiceListKnowledgeAgents

Esempio di richiesta

HTTP

GET https://previewexampleservice.search.windows.net/agents?api-version=2025-08-01-preview

Risposta di esempio

Codice di stato:: 200

{
  "value": [
    {
      "@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>"
        }
      }
    }
  ]
}

Definizioni

Nome	Descrizione
AzureActiveDirectoryApplicationCredentials	Credenziali di un'applicazione registrata creata per il servizio di ricerca, usata per l'accesso autenticato alle chiavi di crittografia archiviate in Azure Key Vault.
AzureOpenAIEmbeddingSkill	Consente di generare un incorporamento vettoriale per un determinato input di testo usando la risorsa Azure OpenAI.
AzureOpenAIModelName	Nome del modello Azure Open AI che verrà chiamato.
AzureOpenAIParameters	Specifica i parametri per la connessione alla risorsa Azure OpenAI.
ErrorAdditionalInfo	Informazioni aggiuntive sull'errore di gestione delle risorse.
ErrorDetail	Dettagli dell'errore.
ErrorResponse	Risposta di errore
InputFieldMappingEntry	Mappatura dei campi di input per una competenza.
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	Specifica la risorsa Azure OpenAI usata per eseguire la pianificazione delle query.
KnowledgeAgentModelKind	Modello di intelligenza artificiale da utilizzare per la pianificazione delle query.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	La configurazione di output per l'agente
KnowledgeAgentRequestLimits	Guardrail per limitare la quantità di risorse utilizzate per una singola richiesta di recupero da parte di un singolo agente.
KnowledgeSourceReference
ListKnowledgeAgentsResult
OutputFieldMappingEntry	Mappatura dei campi di output per una competenza.
SearchIndexerDataNoneIdentity	Cancella la proprietà identity di un'origine dati.
SearchIndexerDataUserAssignedIdentity	Specifica l'identità da utilizzare per un'origine dati.
SearchResourceEncryptionKey	Una chiave di crittografia gestita dal cliente in Azure Key Vault. Le chiavi create e gestite dall'utente possono essere utilizzate per crittografare o decrittografare i dati inattivi, ad esempio indici e mappe di sinonimi.

AzureActiveDirectoryApplicationCredentials

Object

Credenziali di un'applicazione registrata creata per il servizio di ricerca, usata per l'accesso autenticato alle chiavi di crittografia archiviate in Azure Key Vault.

Nome	Tipo	Descrizione
applicationId	string	Un ID applicazione AAD a cui sono state concesse le autorizzazioni di accesso necessarie per Azure Key Vault che deve essere usato per crittografare i dati inattivi. L'ID applicazione non deve essere confuso con l'ID oggetto per l'applicazione AAD.
applicationSecret	string	Chiave di autenticazione dell'applicazione AAD specificata.

AzureOpenAIEmbeddingSkill

Object

Consente di generare un incorporamento vettoriale per un determinato input di testo usando la risorsa Azure OpenAI.

Nome	Tipo	Descrizione
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Frammento URI che specifica il tipo di competenza.
apiKey	string	Chiave API della risorsa Azure OpenAI designata.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identità gestita assegnata dall'utente utilizzata per le connessioni in uscita.
context	string	Rappresenta il livello in cui vengono eseguite le operazioni, ad esempio la radice del documento o il contenuto del documento (ad esempio, /document o /document/content). Il valore predefinito è /document.
deploymentId	string	ID della distribuzione del modello Azure OpenAI nella risorsa designata.
description	string	La descrizione dell'abilità che descrive gli input, gli output e l'utilizzo dell'abilità.
dimensions	integer (int32)	Numero di dimensioni che devono essere presenti negli incorporamenti di output risultanti. Supportato solo nei modelli text-embedding-3 e successivi.
inputs	InputFieldMappingEntry[]	Gli input delle competenze possono essere una colonna nel set di dati di origine o l'output di una competenza a monte.
modelName	AzureOpenAIModelName	Nome del modello di incorporamento distribuito nel percorso deploymentId specificato.
name	string	Il nome della competenza che la identifica in modo univoco all'interno del set di competenze. A un'abilità senza nome definito verrà assegnato un nome predefinito del suo indice in base 1 nell'array di abilità, preceduto dal carattere '#'.
outputs	OutputFieldMappingEntry[]	L'output di una competenza è un campo in un indice di ricerca o un valore che può essere utilizzato come input da un'altra competenza.
resourceUri	string (uri)	URI della risorsa Azure OpenAI.

AzureOpenAIModelName

Enumerazione

Nome del modello Azure Open AI che verrà chiamato.

Valore	Descrizione
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

Object

Specifica i parametri per la connessione alla risorsa Azure OpenAI.

Nome	Tipo	Descrizione
apiKey	string	Chiave API della risorsa Azure OpenAI designata.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identità gestita assegnata dall'utente utilizzata per le connessioni in uscita.
deploymentId	string	ID della distribuzione del modello Azure OpenAI nella risorsa designata.
modelName	AzureOpenAIModelName	Nome del modello di incorporamento distribuito nel percorso deploymentId specificato.
resourceUri	string (uri)	URI della risorsa Azure OpenAI.

ErrorAdditionalInfo

Object

Informazioni aggiuntive sull'errore di gestione delle risorse.

Nome	Tipo	Descrizione
info	object	Informazioni aggiuntive.
type	string	Tipo di informazioni aggiuntive.

ErrorDetail

Object

Dettagli dell'errore.

Nome	Tipo	Descrizione
additionalInfo	ErrorAdditionalInfo[]	Informazioni aggiuntive sull'errore.
code	string	Codice di errore.
details	ErrorDetail[]	Dettagli dell'errore.
message	string	Messaggio di errore.
target	string	Destinazione dell'errore.

ErrorResponse

Object

Risposta di errore

Nome	Tipo	Descrizione
error	ErrorDetail	Oggetto error.

InputFieldMappingEntry

Object

Mappatura dei campi di input per una competenza.

Nome	Tipo	Descrizione
inputs	InputFieldMappingEntry[]	Input ricorsivi utilizzati durante la creazione di un tipo complesso.
name	string	Nome dell'input.
source	string	Origine dell'input.
sourceContext	string	Contesto di origine utilizzato per la selezione degli input ricorsivi.

KnowledgeAgent

Object

Nome	Tipo	Descrizione
@odata.etag	string	ETag dell'agente.
description	string	Descrizione dell'agente.
encryptionKey	SearchResourceEncryptionKey	Descrizione di una chiave di crittografia creata in Azure Key Vault. Questa chiave viene usata per fornire un livello aggiuntivo di crittografia dei dati inattivi per la definizione dell'agente quando si desidera la certezza completa che nessuno, nemmeno Microsoft, possa decrittografarli. Una volta crittografata, la definizione dell'agente rimarrà sempre crittografata. Il servizio di ricerca ignorerà i tentativi di impostare questa proprietà su null. È possibile modificare questa proprietà in base alle esigenze se si desidera ruotare la chiave di crittografia; La definizione dell'agente non sarà interessata. La crittografia con chiavi gestite dal cliente non è disponibile per i servizi di ricerca gratuiti ed è disponibile solo per i servizi a pagamento creati a partire dal 1° gennaio 2019.
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Contiene opzioni di configurazione su come connettersi ai modelli di intelligenza artificiale.
name	string	Il nome dell'agente della conoscenza.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Guardrail per limitare la quantità di risorse utilizzate per una singola richiesta di recupero da parte di un singolo agente.
retrievalInstructions	string	Istruzioni prese in considerazione dall'agente della conoscenza durante lo sviluppo del piano di query.

KnowledgeAgentAzureOpenAIModel

Object

Specifica la risorsa Azure OpenAI usata per eseguire la pianificazione delle query.

Nome	Tipo	Descrizione
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Contiene i parametri specifici dell'endpoint del modello Azure OpenAI.
kind	string: azureOpenAI	Il tipo di modello di intelligenza artificiale.

KnowledgeAgentModelKind

Enumerazione

Modello di intelligenza artificiale da utilizzare per la pianificazione delle query.

Valore	Descrizione
azureOpenAI	Usa i modelli di Azure Open AI per la pianificazione delle query.

KnowledgeAgentOutputConfiguration

Object

Nome	Tipo	Descrizione
answerInstructions	string	Istruzioni prese in considerazione dall'agente della conoscenza durante la generazione delle risposte
attemptFastPath	boolean	Indica se l'agente deve tentare di inviare il messaggio di chat più recente come query diretta alle origini della conoscenza, ignorando le chiamate al modello.
includeActivity	boolean	Indica che i risultati del recupero devono includere informazioni sull'attività.
modality	KnowledgeAgentOutputConfigurationModality	La configurazione di output per l'agente

KnowledgeAgentOutputConfigurationModality

Enumerazione

La configurazione di output per l'agente

Valore	Descrizione
answerSynthesis	Sintetizzare una risposta per il payload della risposta.
extractiveData	Restituisci i dati direttamente dalle fonti di conoscenza senza alterazioni generative.

KnowledgeAgentRequestLimits

Object

Guardrail per limitare la quantità di risorse utilizzate per una singola richiesta di recupero da parte di un singolo agente.

Nome	Tipo	Descrizione
maxOutputSize	integer (int32)	Limita la dimensione massima del contenuto nell'output.
maxRuntimeInSeconds	integer (int32)	L'autonomia massima in secondi.

KnowledgeSourceReference

Object

Nome	Tipo	Descrizione
alwaysQuerySource	boolean	Indica che l'origine della conoscenza deve ignorare la selezione dell'origine e deve essere sempre interrogata al momento del recupero.
includeReferenceSourceData	boolean	Indica se i riferimenti devono includere nel payload i dati strutturati ottenuti durante il recupero.
includeReferences	boolean	Indica se è necessario includere i riferimenti per i dati recuperati da questa origine.
maxSubQueries	integer (int32)	Numero massimo di query che possono essere eseguite contemporaneamente durante il recupero dei dati da questa origine.
name	string	Il nome dell'origine della conoscenza.
rerankerThreshold	number (float)	La soglia di reranker che tutti i documenti recuperati devono soddisfare per essere inclusi nella risposta.

ListKnowledgeAgentsResult

Object

Nome	Tipo	Descrizione
value	KnowledgeAgent[]

OutputFieldMappingEntry

Object

Mappatura dei campi di output per una competenza.

Nome	Tipo	Descrizione
name	string	Nome dell'output definito dalla competenza.
targetName	string	Nome di destinazione dell'output. È facoltativo e predefinito per il nome.

SearchIndexerDataNoneIdentity

Object

Cancella la proprietà identity di un'origine dati.

Nome	Tipo	Descrizione
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Frammento di URI che specifica il tipo di identità.

SearchIndexerDataUserAssignedIdentity

Object

Specifica l'identità da utilizzare per un'origine dati.

Nome	Tipo	Descrizione
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Frammento di URI che specifica il tipo di identità.
userAssignedIdentity	string	L'ID risorsa di Azure completo di un'identità gestita assegnata all'utente, in genere nel formato "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" che avrebbe dovuto essere assegnato al servizio di ricerca.

SearchResourceEncryptionKey

Object

Una chiave di crittografia gestita dal cliente in Azure Key Vault. Le chiavi create e gestite dall'utente possono essere utilizzate per crittografare o decrittografare i dati inattivi, ad esempio indici e mappe di sinonimi.

Nome	Tipo	Descrizione
accessCredentials	AzureActiveDirectoryApplicationCredentials	Credenziali facoltative di Azure Active Directory usate per l'accesso ad Azure Key Vault. Non necessario se si usa l'identità gestita.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Un'identità gestita esplicita da usare per questa chiave di crittografia. Se non viene specificata e la proprietà delle credenziali di accesso è null, viene usata l'identità gestita assegnata dal sistema. Al momento dell'aggiornamento della risorsa, se l'identità esplicita non è specificata, rimane invariata. Se si specifica "none", il valore di questa proprietà viene cancellato.
keyVaultKeyName	string	Nome della chiave di Azure Key Vault da usare per crittografare i dati inattivi.
keyVaultKeyVersion	string	Versione della chiave di Azure Key Vault da usare per crittografare i dati inattivi.
keyVaultUri	string	URI dell'insieme di credenziali delle chiavi di Azure, noto anche come nome DNS, che contiene la chiave da usare per crittografare i dati inattivi. Un URI di esempio potrebbe essere `https://my-keyvault-name.vault.azure.net`.

Condividi tramite

Knowledge Agents - List

Parametri dell'URI

Intestazione della richiesta

Risposte

Esempio

SearchServiceListKnowledgeAgents

Esempio di richiesta

Risposta di esempio

Definizioni

AzureActiveDirectoryApplicationCredentials

AzureOpenAIEmbeddingSkill

AzureOpenAIModelName

AzureOpenAIParameters

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

InputFieldMappingEntry

KnowledgeAgent

KnowledgeAgentAzureOpenAIModel

KnowledgeAgentModelKind

KnowledgeAgentOutputConfiguration

KnowledgeAgentOutputConfigurationModality

KnowledgeAgentRequestLimits

KnowledgeSourceReference

ListKnowledgeAgentsResult

OutputFieldMappingEntry

SearchIndexerDataNoneIdentity

SearchIndexerDataUserAssignedIdentity

SearchResourceEncryptionKey