Hôtes de capacité

Les hôtes de capacité sont des sous-ressources que vous configurez à la fois au niveau du compte Microsoft Foundry et des étendues de projet Foundry. Ils indiquent au service Foundry Agent où stocker et traiter les données de l’agent, notamment :

• Historique des conversations (threads)
• Chargements de fichiers
• Magasins de vecteurs

Conditions préalables

• Un projet Microsoft Foundry
• Si vous utilisez vos propres ressources pour les données de l’agent (configuration de l’agent standard), créez les ressources et connexions requises Azure :
  • Utiliser vos propres ressources
  • Ajouter une nouvelle connexion à votre projet
• Autorisations requises :
  • Rôle de contributeur sur le compte Foundry pour créer des hôtes de fonctionnalités
  • Administrateur d'accès utilisateur ou Propriétaire pour attribuer l’accès aux ressources Azure (pour configurer l’agent standard)
  • Pour plus d’informations, consultez les autorisations Required et Role-based access control (RBAC) dans Microsoft Foundry.

Pourquoi utiliser des hôtes de fonctionnalité ?

Les hôtes de capacité vous permettent d'apporter vos propres ressources Azure au lieu d’utiliser les ressources de plateforme gérées par défaut par Microsoft. Cela vous donne les points suivants :

• Souveraineté des données : conservez toutes les données de l’agent dans votre abonnement Azure.
• Contrôle de sécurité : utilisez vos propres comptes de stockage, bases de données et services de recherche.
• Conformité : répondez aux exigences réglementaires ou organisationnelles spécifiques.

Comment fonctionnent les hôtes de capacité ?

La création d’hôtes de capacité n’est pas nécessaire. Si vous souhaitez que les agents utilisent vos propres ressources Azure, créez des hôtes de capacité à la fois dans les étendues du compte et du projet.

Comportement par défaut (ressources gérées par Microsoft)

Si vous ne créez pas d'hôtes de capacité, le service Agent utilise automatiquement les ressources Azure gérées par Microsoft pour :

• Stockage de threads (historique des conversations, définitions d’agent)
• Stockage de fichiers (documents chargés)
• Recherche vectorielle (incorporations et récupération)

Apportez vos propres ressources

Lorsque vous créez des hôtes de capacité aux niveaux du compte et du projet, vos ressources Azure stockent et traitent les données de l’agent. Il s’agit de la configuration de l’agent standard. Pour la configuration de l’agent standard sécurisé par le réseau, déployez toutes les ressources associées dans la même région que votre réseau virtuel( VNet). Pour obtenir des conseils, consultez Créer un environnement sécurisé par le réseau avec une identité managée par l’utilisateur.

Pour en savoir plus sur la configuration de l’agent standard, consultez La préparation intégrée de l’entreprise avec la configuration de l’agent standard.

Hiérarchie de configuration

Les hôtes de capacité suivent une hiérarchie où des configurations plus spécifiques remplacent des configurations plus larges :

1. Service par défaut (recherche et stockage gérés par Microsoft) : utilisé lorsqu’aucun hôte de fonctionnalité n’est configuré.
2. Hôte de capacité au niveau du compte : fournit des valeurs par défaut partagées pour tous les projets sous le compte.
3. Hôte de fonctionnalité de niveau projet : remplace les valeurs par défaut du service et du niveau du compte pour ce projet spécifique.

Comprendre les contraintes du système de capacités

Lors de la création d’hôtes de fonctionnalités, tenez compte de ces contraintes importantes pour éviter les conflits :

• Un hôte de capacité par étendue : chaque compte et chaque projet ne peuvent avoir qu’un seul hôte de capacité actif. Si vous essayez de créer un deuxième hôte de fonctionnalité avec un nom différent dans la même étendue, vous obtenez un conflit 409.

• Vous ne pouvez pas mettre à jour les configurations : si vous avez besoin de modifier la configuration, supprimez l’hôte de fonctionnalité existant et recréez-le.

Créer des connexions pour les hôtes de capacité

Les hôtes de fonctionnalité référencent les noms de connexion que vous créez dans votre compte et projet Foundry. Avant de configurer un hôte de capacité de projet pour la configuration de l’agent standard, créez des connexions pour les ressources qui stockent les données de l’agent :

• Thread storage : connexion Azure Cosmos DB
• Stockage de fichiers : connexion au stockage Azure
• magasin Vector : connexion Recherche Azure AI

Si vous souhaitez utiliser des déploiements de modèles à partir de votre propre ressource OpenAI Azure, créez également une connexion OpenAI Azure.

Pour ajouter des connexions dans le portail Foundry, consultez Ajouter une nouvelle connexion à votre projet.

Configurer des hôtes de capacité

Actuellement, vous gérez les hôtes de capacité à l’aide de l’API REST. La prise en charge du Kit de développement logiciel (SDK) pour la gestion des fonctionnalités hôtes n’est pas disponible.

Propriétés requises (hôte de fonctionnalité de projet)

Pour utiliser vos propres ressources pour les données de l’agent (configuration de l’agent standard), configurez l’hôte de capacité de projet avec les propriétés suivantes :

Propriété facultative

Hôte de fonctionnalité de compte

Utilisez un hôte de capacité de compte pour activer le Service Agent et, si vous le souhaitez, définir les valeurs par défaut que les projets peuvent hériter.

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

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

Référence : API REST de gestion des comptes Foundry

hôte de fonctionnalité Project

Cette configuration remplace les paramètres de service par défaut et tous les paramètres au niveau du compte. Tous les agents de ce projet utilisent vos ressources spécifiées :

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"]
  }
}

Référence : Hôtes de capacités du projet - Créer ou mettre à jour

Facultatif : valeurs par défaut au niveau du compte avec remplacements de projet

Définissez les valeurs par défaut partagées au niveau du compte qui s’appliquent à tous les projets :

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"]
  }
}

Vérifier votre configuration

Procédez comme suit pour vérifier que les hôtes de capacité sont configurés correctement :

1. Obtenez l’hôte de capacité du compte et vérifiez qu’il existe.

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

2. Obtenez l’hôte de capacité du projet et confirmez qu’il fait référence aux noms de connexion attendus.

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

3. Testez votre configuration en créant un agent de test et en exécutant une conversation. Vérifiez que :

   • Les threads de conversation apparaissent dans votre Azure Cosmos DB
   • Les fichiers chargés apparaissent dans votre compte stockage Azure
   • Les données vectorielles s’affichent dans votre index de Recherche Azure AI

4. Si vous mettez à jour les connexions ou souhaitez modifier l’emplacement où les données sont stockées, supprimez et recréez les hôtes de capacité avec la configuration mise à jour.

Supprimer les hôtes de capacités

Supprimer un hôte de capacité au niveau du compte

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

Supprimer un hôte de fonctionnalité au niveau du projet

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

Dépannage

Si vous rencontrez des problèmes lors de la création d’hôtes de capacité, cette section fournit des solutions aux problèmes et erreurs les plus courants.

Erreurs de conflit HTTP 409

Problème : Plusieurs hôtes de capacité par étendue

Symptômes : Vous recevez une erreur 409 Conflit lors de la tentative de création d’un hôte de fonctionnalité, même si vous pensez que la portée est vide.

Message d’erreur :

{
  "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."
  }
}

Cause profonde : Chaque compte et chaque projet ne peuvent avoir qu’un seul hôte de capacité actif. Vous essayez de créer un hôte de capacité avec un nom différent quand il en existe déjà un à la même portée.

Solution:

1. Vérifier les hôtes de capacités existants - Examiner la portée pour déterminer ce qui existe déjà
2. Utiliser un nom cohérent : vérifiez que vous utilisez le même nom dans toutes les demandes pour la même étendue
3. Passez en revue vos besoins : déterminez si l’hôte de capacité existant répond à vos besoins

Étapes de validation : Utilisez les requêtes GET dans Vérifier votre configuration pour vérifier si un hôte de fonctionnalité existe déjà dans l’étendue cible.

Problème : opérations simultanées en cours

Symptômes: Vous recevez une erreur de conflit 409 indiquant qu’une autre opération est en cours d’exécution.

Message d’erreur :

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

Cause première : Vous essayez de créer un hôte de capacité alors qu'une autre opération (mise à jour, suppression, modification) est en cours au même niveau.

Solution:

1. Attendez la fin de l’opération actuelle : vérifiez l’état des opérations en cours
2. Surveiller la progression de l’opération - Utiliser l’API d’opérations pour suivre l’achèvement
3. Implémenter une logique de reprise - Utiliser un repli exponentiel pour les conflits temporaires

Surveillance des opérations :

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

Meilleures pratiques pour la prévention des conflits

1. Validation de la pré-demande

Vérifiez toujours l’état actuel avant d’apporter des modifications :

• Interroger des hôtes de capacité existants dans l’étendue cible
• Vérifier les opérations en cours
• Comprendre la configuration actuelle

2. Implémenter une logique de reprise avec un recul exponentiel

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. Comprendre le comportement idempotent

Le système prend en charge les demandes de création idempotentes :

• Même nom + même configuration → Renvoie la ressource existante (200 OK)
• Même nom + autre configuration → Renvoie la requête incorrecte 400
• Le nom différent → renvoie le conflit 409

4. Flux de travail de modification de configuration

Étant donné que les mises à jour ne sont pas prises en charge, suivez cette séquence pour les modifications de configuration :

1. Supprimer l’hôte de fonctionnalité existant
2. Attendez la fin de la suppression
3. Créer un nouvel hôte de capacité avec les configurations souhaitées

Scénarios courants

• Development et test : utilisez des ressources gérées par Microsoft. Aucune configuration d’hôte de capacité n’est nécessaire.
• Production avec les exigences de conformité : créez des hôtes de ressources avec vos propres Azure Cosmos DB, Azure Storage et Azure AI Search.
• Ressources partagées entre les projets : configurez les valeurs par défaut au niveau du compte, puis remplacez-les au niveau du projet en fonction des besoins.

Étapes suivantes

• Configuration de l’agent standard
• Configurer votre environnement
• Ajouter une nouvelle connexion à votre projet