Knowledge Agents - Create

Servizio:: Search Service

Versione API:: 2025-05-01-preview

Crea un nuovo agente.

POST {endpoint}/agents?api-version=2025-05-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 per facilitare il debug.

Corpo della richiesta

Nome	Necessario	Tipo	Descrizione
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Contiene opzioni di configurazione su come connettersi ai modelli di intelligenza artificiale.
name	True	string	Il nome dell'agente della conoscenza.
targetIndexes	True	KnowledgeAgentTargetIndex[]
@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 il 1° gennaio 2019.
requestLimits		KnowledgeAgentRequestLimits	Guardrail per limitare la quantità di risorse utilizzate per una singola richiesta di recupero da parte di un singolo agente.

Risposte

Nome	Tipo	Descrizione
201 Created	KnowledgeAgent	Creazione di un agente
Other Status Codes	ErrorResponse	Risposta di errore.

Esempio

SearchServiceCreateKnowledgeAgent

Esempio di richiesta

HTTP

POST https://previewexampleservice.search.windows.net/agents?api-version=2025-05-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"
    }
  ],
  "targetIndexes": [
    {
      "indexName": "preview-test",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ],
  "requestLimits": {
    "maxRuntimeInSeconds": 60,
    "maxOutputSize": 100000
  },
  "@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."
}

Risposta di esempio

Codice di stato:: 201

{
  "@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": "api-key",
        "modelName": "gpt-4.1-nano"
      }
    }
  ],
  "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 input di testo specificato usando la risorsa OpenAI di Azure.
AzureOpenAIModelName	Nome del modello di Azure Open AI che verrà chiamato.
AzureOpenAIParameters	Specifica i parametri per la connessione alla risorsa OpenAI di Azure.
ErrorAdditionalInfo	Informazioni aggiuntive sull'errore di gestione delle risorse.
ErrorDetail	Dettagli dell'errore.
ErrorResponse	Risposta di errore
InputFieldMappingEntry	Mapping 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.
KnowledgeAgentRequestLimits	Guardrail per limitare la quantità di risorse utilizzate per una singola richiesta di recupero da parte di un singolo agente.
KnowledgeAgentTargetIndex
OutputFieldMappingEntry	Mapping dei campi di output per una competenza.
SearchIndexerDataNoneIdentity	Cancella la proprietà Identity di un'origine dati.
SearchIndexerDataUserAssignedIdentity	Specifica l'identità di un'origine dati da usare.
SearchResourceEncryptionKey	Una chiave di crittografia gestita dal cliente in Azure Key Vault. Le chiavi create e gestite possono essere usate per crittografare o decrittografare i dati inattivi, ad esempio indici e mappe sinonimi.

AzureActiveDirectoryApplicationCredentials

Oggetto

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	ID applicazione AAD a cui sono state concesse le autorizzazioni di accesso necessarie all'insieme di credenziali delle chiavi di Azure da usare durante la crittografia dei 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

Oggetto

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

Nome	Tipo	Descrizione
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Frammento URI che specifica il tipo di competenza.
apiKey	string	Chiave API della risorsa OpenAI di Azure designata.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identità gestita assegnata dall'utente usata 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 OpenAI di Azure nella risorsa designata.
description	string	Descrizione della competenza che descrive gli input, gli output e l'utilizzo della competenza.
dimensions	integer (int32)	Numero di dimensioni che devono essere presenti negli incorporamenti di output risultanti. Supportato solo nei modelli text-embedding-3 e versioni successive.
inputs	InputFieldMappingEntry[]	Gli input delle competenze possono essere una colonna nel set di dati di origine o l'output di una competenza upstream.
modelName	AzureOpenAIModelName	Nome del modello di incorporamento distribuito nel percorso deploymentId specificato.
name	string	Nome della competenza che lo identifica in modo univoco all'interno del set di competenze. A una competenza senza nome definito verrà assegnato un nome predefinito del relativo indice basato su 1 nella matrice di competenze, 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 OpenAI di Azure.

AzureOpenAIModelName

Enumerazione

Nome del modello di 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

Oggetto

Specifica i parametri per la connessione alla risorsa OpenAI di Azure.

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

ErrorAdditionalInfo

Oggetto

Informazioni aggiuntive sull'errore di gestione delle risorse.

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

ErrorDetail

Oggetto

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

Oggetto

Risposta di errore

Nome	Tipo	Descrizione
error	ErrorDetail	Oggetto error.

InputFieldMappingEntry

Oggetto

Mapping 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 usato per la selezione di input ricorsivi.

KnowledgeAgent

Oggetto

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 il 1° gennaio 2019.
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Contiene opzioni di configurazione su come connettersi ai modelli di intelligenza artificiale.
name	string	Il nome dell'agente della conoscenza.
requestLimits	KnowledgeAgentRequestLimits	Guardrail per limitare la quantità di risorse utilizzate per una singola richiesta di recupero da parte di un singolo agente.
targetIndexes	KnowledgeAgentTargetIndex[]

KnowledgeAgentAzureOpenAIModel

Oggetto

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.

KnowledgeAgentRequestLimits

Oggetto

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.

KnowledgeAgentTargetIndex

Oggetto

Nome	Tipo	Descrizione
defaultIncludeReferenceSourceData	boolean	Indica se devono essere inclusi i dati di origine di riferimento.
defaultMaxDocsForReranker	integer (int32)	Limita il numero di documenti considerati per la classificazione.
defaultRerankerThreshold	number (float) minimum: 0 maximum: 4	Una soglia per il riposizionamento dei risultati (intervallo: 0-4).
indexName	string	Nome dell'indice di destinazione.

OutputFieldMappingEntry

Oggetto

Mapping 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 il nome predefinito è .

SearchIndexerDataNoneIdentity

Oggetto

Cancella la proprietà Identity di un'origine dati.

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

SearchIndexerDataUserAssignedIdentity

Oggetto

Specifica l'identità di un'origine dati da usare.

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

SearchResourceEncryptionKey

Oggetto

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

Nome	Tipo	Descrizione
accessCredentials	AzureActiveDirectoryApplicationCredentials	Credenziali facoltative di Azure Active Directory usate per l'accesso ad Azure Key Vault. Non obbligatorio se invece si usa l'identità gestita.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Identità gestita esplicita da usare per questa chiave di crittografia. Se non specificato e la proprietà delle credenziali di accesso è Null, viene usata l'identità gestita assegnata dal sistema. Se l'identità esplicita non viene specificata, l'aggiornamento alla risorsa rimane invariato. 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	L'URI dell'insieme di credenziali delle chiavi di Azure, detto anche 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`.