Host di funzionalità

Gli host di funzionalità sono sotto-risorse configurate sia nell'account Microsoft Foundry che negli ambiti del progetto Foundry. Indicano al servizio agente Foundry dove archiviare ed elaborare i dati dell'agente, tra cui:

• Cronologia conversazioni (thread)
• Caricamenti di file
• Archivi vettoriali

Prerequisiti

• Un progetto Microsoft Foundry
• Se si usano risorse personalizzate per i dati dell'agente (configurazione dell'agente standard), creare le risorse e le connessioni di Azure necessarie:
  • Usare le proprie risorse
  • Aggiungere una nuova connessione al progetto
• Autorizzazioni necessarie:
  • Ruolo Collaboratore nell'account Foundry per creare host delle funzionalità
  • Ruolo Amministratore accesso utenti o Proprietario per assegnare l'accesso alle risorse di Azure (per la configurazione dell'agente standard)
  • Per informazioni dettagliate, vedere Autorizzazioni necessarie e Controllo degli accessi in base al ruolo in Microsoft Foundry.

Perché usare gli host di funzionalità?

Gli host di funzionalità consentono di usare le proprie risorse di Azure invece di usare le risorse predefinite della piattaforma gestita da Microsoft. In questo modo è possibile:

• Sovranità dei dati : mantenere tutti i dati dell'agente all'interno della sottoscrizione di Azure.
• Controllo di sicurezza : usare account di archiviazione, database e servizi di ricerca personalizzati.
• Conformità : soddisfa requisiti normativi o organizzativi specifici.

Come funzionano gli host di funzionalità?

La creazione di host di funzionalità non è necessaria. Se vuoi che gli agenti utilizzino le tue risorse di Azure, crea host di funzionalità sia a livello dell'account che del progetto.

Comportamento predefinito (risorse gestite da Microsoft)

Se non si creano host di funzionalità, il servizio Agent usa automaticamente le risorse di Azure gestite da Microsoft per:

• Archiviazione thread (cronologia delle conversazioni, definizioni agente)
• Archiviazione file (documenti caricati)
• Ricerca vettoriale (incorporamenti e recupero)

Risorse personali

Quando si creano host di funzionalità sia a livello di account che di progetto, le risorse di Azure archiviano ed elaborano i dati dell'agente. Questa è la configurazione standard dell'agente. Per la configurazione dell'agente standard protetto dalla rete, distribuire tutte le risorse correlate nella stessa area della rete virtuale.For network-secured standard setup, deploy all related resources in the same region as your virtual network (VNet). Per indicazioni, vedere Creare un nuovo ambiente protetto dalla rete con identità gestita dall'utente.

Per altre informazioni sulla configurazione dell'agente standard, vedere Idoneità aziendale predefinita con la configurazione dell'agente standard.

Gerarchia di configurazione

Gli host di funzionalità seguono una gerarchia in cui le configurazioni più specifiche sostituiscono quelle più ampie:

1. Impostazioni predefinite del servizio (ricerca e archiviazione gestite da Microsoft): usato quando non è configurato alcun host di funzionalità.
2. Host di funzionalità a livello di account: fornisce impostazioni predefinite condivise per tutti i progetti nell'account.
3. Host di funzionalità a livello di progetto: esegue l'override delle impostazioni predefinite a livello di account e di servizio per tale progetto specifico.

Informazioni sui vincoli host delle funzionalità

Quando si creano host di funzionalità, tenere presente questi vincoli importanti per evitare conflitti:

• Un host di funzionalità per ambito: ogni account e ogni progetto può avere un solo host di funzionalità attive. Se si tenta di creare un secondo host di funzionalità con un nome diverso nello stesso ambito, si verifica un conflitto 409.

• Non è possibile aggiornare le configurazioni: se è necessario modificare la configurazione, eliminare l'host di funzionalità esistente e ricrearlo.

Creare connessioni per gli host di funzionalità

Gli host di funzionalità fanno riferimento a nomi di connessione creati nel progetto e nell'account Foundry. Prima di configurare un host di funzionalità di progetto per la configurazione dell'agente standard, creare connessioni per le risorse che archiviano i dati dell'agente:

• Archiviazione thread: connessione di Azure Cosmos DB
• Archiviazione file: Connessione ad Azure Storage
• Archivio vettoriale: connessione di Azure AI Search

Se desideri usare le distribuzioni di modelli dalla tua risorsa Azure OpenAI, crea anche una connessione Azure OpenAI.

Per aggiungere connessioni nel portale foundry, vedere Aggiungere una nuova connessione al progetto.

Configurare gli host di funzionalità

Attualmente, gli host di funzionalità vengono gestiti usando l'API REST. Il supporto SDK per la gestione dell'host delle funzionalità non è disponibile.

Proprietà obbligatorie (host di funzionalità del progetto)

Per usare le proprie risorse per i dati agente (configurazione dell'agente standard), configurare l'host di funzionalità del progetto con le proprietà seguenti:

Proprietà facoltativa

Host d funzionalità dell'account

Usare un host di funzionalità dell'account per abilitare il servizio Agent e ,facoltativamente, definire le impostazioni predefinite che i progetti possono ereditare.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents"
  }
}

Informazioni di riferimento: API REST di gestione degli account Foundry

Host di funzionalità del progetto

Questa configurazione sostituisce le impostazioni predefinite del servizio e tutte le impostazioni a livello di account. Tutti gli agenti in questo progetto useranno le risorse specificate:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["my-cosmos-db-connection"],
    "vectorStoreConnections": ["my-ai-search-connection"],
    "storageConnections": ["my-storage-account-connection"],
    "aiServicesConnections": ["my-azure-openai-connection"]
  }
}

Riferimento: Capacità dell'host del progetto - Creare o aggiornare

Facoltativo: impostazioni predefinite a livello di account con override del progetto

Impostare le impostazioni predefinite condivise a livello di account applicabili a tutti i progetti:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["shared-cosmosdb-connection"],
    "vectorStoreConnections": ["shared-ai-search-connection"],
    "storageConnections": ["shared-storage-connection"]
  }
}

Verificare la configurazione

Usare questi passaggi per verificare che gli host di funzionalità siano configurati correttamente:

1. Ottenere l'host della funzionalità dell'account e verificare che esista.

   GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts?api-version=2025-06-01
   

2. Ottieni l'host delle funzionalità del progetto e verifica che faccia riferimento ai nomi di connessione previsti.

   GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts?api-version=2025-06-01
   

3. Testare la configurazione creando un agente di test ed eseguendo una conversazione. Confermare che:

   • I thread di conversazione vengono visualizzati in Azure Cosmos DB
   • I file caricati vengono visualizzati nell'account di archiviazione di Azure
   • I dati vettoriali vengono visualizzati nell'indice di Ricerca di intelligenza artificiale di Azure

4. Se si aggiornano le connessioni o si vuole modificare la posizione in cui vengono archiviati i dati, eliminare e ricreare gli host delle funzionalità con la configurazione aggiornata.

Eliminare gli host di funzionalità

Eliminare un host di funzionalità a livello di account

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

Eliminare un host di funzionalità a livello di progetto

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

Risoluzione dei problemi

Se si verificano problemi durante la creazione di host di funzionalità, questa sezione fornisce soluzioni ai problemi e agli errori più comuni.

Errori di conflitto HTTP 409

Problema: più host di funzionalità per ambito

Sintomi: viene visualizzato un errore 409 Conflict quando si tenta di creare un host di funzionalità, anche se si ritiene che l'ambito sia vuoto.

Messaggio di errore:

{
  "error": {
    "code": "Conflict",
    "message": "There is an existing Capability Host with name: existing-host, provisioning state: Succeeded for workspace: /subscriptions/.../workspaces/my-workspace, cannot create a new Capability Host with name: new-host for the same ClientId."
  }
}

Causa radice: ogni account e ogni progetto può avere un solo host di funzionalità attive. Si sta provando a creare un host di funzionalità con un nome diverso quando ne esiste già uno nello stesso ambito.

Soluzione:

1. Controllare gli host di funzionalità esistenti: eseguire una query sull'ambito per vedere cosa esiste già
2. Usare la denominazione coerente: assicurarsi di usare lo stesso nome in tutte le richieste per lo stesso ambito
3. Esaminare i requisiti: determinare se l'host di funzionalità esistente soddisfa le proprie esigenze

Passaggi di convalida: Usare le richieste GET in Verificare la configurazione per verificare se un host di funzionalità esiste già nell'ambito di destinazione.

Problema: operazioni simultanee in corso

Sintomi: viene visualizzato un errore di conflitto 409 che indica che è in esecuzione un'altra operazione.

Messaggio di errore:

{
  "error": {
    "code": "Conflict", 
    "message": "Create: Capability Host my-host is currently in non creating, retry after its complete: /subscriptions/.../workspaces/my-workspace"
  }
}

Causa radice: si sta tentando di creare un host di funzionalità mentre è in corso un'altra operazione (aggiornamento, eliminazione, modifica) nello stesso ambito.

Soluzione:

1. Attendere il completamento dell'operazione corrente: controllare lo stato delle operazioni in corso
2. Monitorare lo stato dell'operazione: usare l'API delle operazioni per tenere traccia del completamento
3. Implementare la logica di ripetizione dei tentativi - Usare il backoff esponenziale per i conflitti temporanei

Monitoraggio delle operazioni:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/locations/{location}/operationResults/{operationId}?api-version=2025-06-01

Procedure consigliate per la prevenzione dei conflitti

1. Convalida della pre-richiesta

Verificare sempre lo stato corrente prima di apportare modifiche:

• Eseguire query sugli host di funzionalità esistenti nell'ambito di destinazione
• Controllare la presenza di eventuali operazioni in corso
• Informazioni sulla configurazione corrente

2. Implementare la logica di retry con backoff esponenziale

try 
{
    var response = await CreateCapabilityHostAsync(request);
    return response;
}
catch (HttpRequestException ex) when (ex.Message.Contains("409"))
{
    if (ex.Message.Contains("existing Capability Host with name"))
    {
        // Handle name conflict - check if existing resource is acceptable
        var existing = await GetExistingCapabilityHostAsync();
        if (IsAcceptable(existing))
        {
            return existing; // Use existing resource
        }
        else
        {
            throw new InvalidOperationException("Scope already has a capability host with different name");
        }
    }
    else if (ex.Message.Contains("currently in non creating"))
    {
        // Handle concurrent operation - implement retry with backoff
        await Task.Delay(TimeSpan.FromSeconds(30));
        return await CreateCapabilityHostAsync(request); // Retry once
    }
}

3. Comprendere il comportamento idempotent

Il sistema supporta le richieste di creazione idempotent:

• Stesso nome e stessa configurazione → Restituisce la risorsa esistente (200 OK)
• Stesso nome e configurazione diversa → restituisce 400 richiesta non valida
• Nome diverso → Restituisce 409 conflitto

4. Flusso di lavoro di modifica della configurazione

Poiché gli aggiornamenti non sono supportati, seguire questa sequenza per le modifiche alla configurazione:

1. Eliminare l'host di funzionalità esistente
2. Attendere il completamento dell'eliminazione
3. Creare un nuovo host di funzionalità con la configurazione desiderata

Scenari comuni

• Sviluppo e test: usare le risorse gestite da Microsoft. Non è necessaria alcuna configurazione di host di capacità.
• Produzione con requisiti di conformità: creare host delle funzionalità con Azure Cosmos DB, Archiviazione e AI Search.
• Risorse condivise tra progetti: configurare le impostazioni predefinite a livello di account, quindi eseguire l'override a livello di progetto in base alle esigenze.

Passaggi successivi

• Configurazione dell'agente standard
• Configurare l'ambiente
• Aggiungere una nuova connessione al progetto