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
• Chargements de fichiers
• Bases de données vectorielles

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 la configuration de 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 conversation (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 sécuriser votre service Agent, consultez Configurer un réseau privé pour Foundry Agent Service.

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é opèrent à deux niveaux distincts :

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 : active le service Agent au niveau du compte.
3. Hôte de capacité au niveau du projet : définit quelles ressources BYO le service Agent utilise pour ce projet spécifique.

Comprendre les contraintes de l’hôte de capacité

Lors de la création d’hôtes de capacité, 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 autre nom dans la même étendue, vous recevrez une erreur 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.

• Condition préalable à la création d’un hôte de fonctionnalités de projet : vous ne pouvez pas créer d’hôte de fonctionnalités de projet tant qu’il n’existe pas déjà un hôte de fonctionnalités au niveau du compte.

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

Les hôtes de capacités référencent les noms de connexion que vous créez dans votre compte Foundry et votre projet. 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 :

• Stockage de conversation : connexion Azure Cosmos DB
• Stockage de fichiers : connexion stockage Azure
• Magasin de vecteurs : 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.

Propriétés de connexion requises

Pour que le service Agent résolve et utilise correctement vos ressources au moment de l’exécution, chaque connexion référencée par un hôte de capacité doit avoir les propriétés suivantes remplies :

L’exemple suivant montre une connexion stockage Azure correctement configurée :

{
  "properties": {
    "authType": "AAD",
    "category": "AzureStorageAccount",
    "target": "https://{storageAccountName}.blob.core.windows.net/",
    "metadata": {
      "ResourceId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}"
    }
  }
}

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ôte 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 capacité de compte

Utilisez un hôte de capacité de compte pour activer le service Agent au niveau du compte.

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 capacité de projet

L’hôte de capacité du projet est ce que le service Agent lit pour déterminer les ressources BYO à utiliser pour un projet. Tous les agents de ce projet utilisent les ressources référencées ici :

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é de projet - Créer ou mettre à jour

Facultatif : connexions au niveau du compte avec des hôtes prenant en charge les projets

Vous pouvez également définir des connexions au niveau du compte. Lorsqu’un nouveau projet est créé sous ce compte, ces connexions sont héritées par le projet. Toutefois, la configuration de l’hôte de capacité du projet n’est pas héritée : vous devez toujours créer explicitement un hôte de capacité de projet et indiquer les connexions que vous souhaitez qu’Agent Service utilise pour ce projet.

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é de compte et confirmez son existence.

   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 conversations 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 des hôtes de capacité

Supprimer un hôte de fonctionnalité 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 de conflit 409 lorsque vous essayez de créer un hôte de capacité, même si vous pensez que l’étendue 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 racine: 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 alors qu’il en existe déjà un dans le même domaine.

Solution:

1. Vérifier les hôtes de capacités existants – Interroger l’étendue pour voir 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 fondamentale: Vous essayez de créer un hôte de fonction tandis qu'une autre opération (mise à jour, suppression, modification) est en cours dans la même étendue.

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 recul 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 nouvelle tentative avec temporisation exponentielle

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 requêtes 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 hôte de fonctionnalité avec la configuration souhaitée

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 exigences de conformité : créez des instances avec vos propres Azure Cosmos DB, solutions de stockage et options de recherche intelligente.
• Ressources partagées entre les projets : configurez les connexions au niveau du compte, puis créez un hôte de capacité de projet pour chaque projet qui référence explicitement ces connexions.

Étapes suivantes

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