Host di funzionalità

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

• Cronologia delle conversazioni (thread)
• Caricamenti di file
• Archivi di vettori

Prerequisiti

• Progetto Microsoft Foundry
• Se si usano risorse personalizzate per i dati dell'agente (configurazione dell'agente standard), creare le risorse e le connessioni necessarie Azure:
  • Usare le proprie risorse
  • Aggiungere una nuova connessione al progetto
• Autorizzazioni necessarie:
  • Ruolo Collaboratore nell'account Foundry per creare host delle funzionalità
  • Amministratore accesso utente o Proprietario per assegnare l'accesso alle risorse di Azure (per la configurazione standard dell'agente)
  • Per informazioni dettagliate, vedere le Required permissions e il Role-based access control (RBAC) in Microsoft Foundry.

Perché usare gli host di funzionalità?

Gli host di funzionalità consentono di utilizzare le proprie risorse di Azure anziché utilizzare le risorse della piattaforma gestite da Microsoft per impostazione predefinita. In questo modo è possibile:

• Sovranità dei dati: mantenere tutti i dati dell'agente all'interno della sottoscrizione 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 si vuole che gli agenti usino le proprie risorse Azure, creare host di funzionalità sia nell'account che negli ambiti del progetto.

Comportamento predefinito (risorse gestite da Microsoft)

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

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

Bring-your-own Resources

Quando si creano host di funzionalità sia a livello di account che di progetto, le risorse 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 Service (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 capacità a livello di progetto : esegue l'override del livello di account 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.

• Prerequisito host della funzionalità dell'account: non è possibile creare un host delle funzionalità del progetto a meno che non esista già un host delle funzionalità a livello di account.

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 di file: connessione di Archiviazione di Azure
• Archivio vettoriale: connessione di Azure AI Search

Se si vogliono usare distribuzioni di modelli dalla propria risorsa OpenAI Azure, creare anche una connessione OpenAI Azure.

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 di 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 della funzionalità di 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: Funzionalità degli host di progetto - Creazione o aggiornamento

Facoltativo: impostazioni predefinite a livello di account con sovrascritture a livello di 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 di 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. Ottenere l'host di funzionalità del progetto e confermare 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 nella Azure Cosmos DB
   • I file caricati vengono visualizzati nell'account Archiviazione di Azure
   • I dati vettoriali vengono visualizzati nell'indice Azure AI Search

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 - 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 preliminare della richiesta

Verificare sempre lo stato corrente prima di apportare modifiche:

• Eseguire query sugli host di funzionalità esistenti nell'ambito di destinazione
• Verificare 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
    }
}

Comprendere il comportamento idempotente

Il sistema supporta le richieste di creazione idempotenti:

• 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: Utilizzare risorse gestite da Microsoft. Non è necessaria alcuna configurazione host delle capacità.
• Produzione con requisiti di conformità: creare host con funzionalità utilizzando Azure Cosmos DB, Azure Storage 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