Plan d’agent de configuration

Le blueprint de l’agent définit l’identité, les autorisations et les exigences d’infrastructure de votre agent. Créez chaque instance d’agent à partir de ce blueprint d’agent.

Pour plus d’informations sur l’identité de l’agent 365, voir l’identité de l’agent 365.

Prérequis

Avant de commencer, vérifiez que vous disposez des conditions préalables suivantes :

1. Agent 365 CLI - Voir installation de l’Agent 365 CLI.

2. Autorisations requises :

   • Utilisateur client valide avec l’un des rôles suivants :
     • Administrateur général
     • Administrateur d'identifiant d'agent
     • Développeur d'identifiant d'agent
   • Accès à un abonnement Azure avec des autorisations pour créer des ressources

3. Fichier valide a365.config.json dans votre répertoire de travail, configuré via cette étape : Configuration de l’Agent 365.

Créer un schéma d’agent

Utilisez la commande a365 setup pour créer des ressources Azure et inscrire votre blueprint agent. Le blueprint définit l’identité de votre assistant, ses autorisations et ses besoins en matière d’infrastructure. Cette étape établit la base du déploiement et de l’exécution de votre agent dans Azure.

Exécuter le programme d’installation

Exécutez la commande de configuration :

a365 setup -h

La commande offre plusieurs options. Vous pouvez compléter toute la configuration en une seule commande en utilisant a365 setup all ou en choisissant des options plus granulaires.

L’ensemble du processus de mise en place effectue les opérations suivantes :

1. Creates Azure infrastructure (s'il n'existe pas encore) :

   • Groupe de ressources
   • Plan App Service avec référence SKU spécifiée
   • Azure Application web avec identité managée activée

2. Enregistre le blueprint de l'agent :

   • Crée le modèle de l’agent dans votre instance Microsoft Entra
   • Crée des enregistrements d'applications Microsoft Entra
   • Configure l’identité de l’assistant avec les autorisations requises

3. Configure les autorisations API :

   • Configurer des étendues Microsoft Graph API
   • Configure les autorisations de l’API Messaging Bot
   • Applique des autorisations héritées pour les instances d'agent

4. Met à jour les fichiers config :

   • Sauvegarde les identifiants et points de terminaison générés dans un nouveau fichier de votre répertoire de travail appelé a365.generated.config.json
   • Enregistre les informations sur l’identité managée et les ressources

Vérifier l’installation

Une fois la configuration terminée, vous voyez un résumé qui montre toutes les étapes complétées. Vérifiez les ressources créées :

1. Vérifier la configuration générée :

   a365 config display -g
   

   La production attendue inclut ces valeurs critiques :

   {
   "managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "agentBlueprintClientSecretProtected": true,
   "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMessagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
   "resourceConsents": [],
   "completed": true,
   "completedAt": "xxxx-xx-xxTxx:xx:xxZ",
   "cliVersion": "x.x.xx"
   }
   

   Champs clés à vérifier :

   Terrain	Objectif	Que vérifier
   managedIdentityPrincipalId	Authentification d'identité gérée par Azure	Ça devrait être un GUID valide
   agentBlueprintId	L’identifiant unique de votre agent	Utilisé dans le portail développeur et le centre d’administration
   agentBlueprintObjectId	Le plan de Microsoft Entra ID
   botMessagingEndpoint	Routage de messages	Où Teams/Outlook envoient des messages à votre agent
   agentBlueprintClientSecret	Secret d’authentification	Devrait exister (la valeur est masquée)
   resourceConsents	Autorisations des API	Doit contenir des ressources telles que Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API
   completed	Statut de la configuration	Cela devrait être true

2. Vérifiez les ressources Azure dans Azure Portal :

   Ou utilisez la az resource list commande PowerShell.

   # List all resources in your resource group
   az resource list --resource-group <your-resource-group> --output table
   

   Vérifiez que les ressources suivantes sont créées :

   • Groupe de ressources :

     • Aller dans Groupes de ressources Sélectionner> votre groupe de ressources
     • Vérifiez qu’il contient votre plan App Service et votre application web

   • Plan App Service :

     • Accédez à App Services>Plans App Service
     • Recherchez votre plan et vérifiez que le niveau tarifaire correspond à votre SKU de configuration

   • Web App :

     • Accédez à App Services>Web Apps
     • Recherchez votre Web App, puis accédez à Paramètres>Identité>Attribué par le système
     • Vérifier que l’état est défini sur Activé
     • Notez que l’ID d’objet (principal) correspond à managedIdentityPrincipalId

3. Vérifier les applications Microsoft Entra dans Azure Portal :

   Accédez à Azure Active Directory>App registrations>All applications :

   • Recherchez le blueprint de votre agent en utilisant agentBlueprintId

   • Ouvrez l’application et sélectionnez Autorisations API

   • Vérifiez que les autorisations sont accordées avec des coches vertes :

     • Microsoft Graph (autorisations déléguées et d’application)
     • Autorisations de l’API Messaging Bot

   • Toutes les autorisations affichent « Accordées pour [Votre locataire] »

4. Vérifier le fichier de configuration généré créé :

   Il devrait y avoir un fichier nommé a365.generated.config.json contenant toutes les données de configuration.

   Vous pouvez tester son existence en utilisant la commande PowerShell Test-Path .

   # Check file exists
   Test-Path a365.generated.config.json
   # Should return: True
   

   Important

   Sauvegardez les fichiers a365.config.json et a365.generated.config.json. Vous avez besoin de ces valeurs pour le déploiement et le dépannage.

5. Vérifiez que l'application Verify Web a l’identité gérée activée :

   Utilisez la az webapp identity show commande pour vérifier si l’identité gérée est activée.

   az webapp identity show --name <your-web-app> --resource-group <your-resource-group>
   

   Attendu :

   {
   "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "type": "SystemAssigned"
   }
   

6. Vérifiez le modèle de l’agent enregistré dans Entra :

   Dans Microsoft Entra centre d’administration, recherchez votre agentBlueprintId ou recherchez par nom.

   Vérifiez que :

   ✅ L’enregistrement d’applications et l’application d’entreprise apparaissent
   ✅ Sur le blueprint d’enregistrement de l’application, l’onglet des autorisations API affiche toutes les permissions
   ✅ Le statut indique « Accordé pour [Votre locataire] »

Pour plus d’aide, voir :

• problèmes de configuration
• Problèmes d’application client personnalisée

Étapes suivantes

Déploie le code de ton agent dans le cloud :

Résolution des problèmes

Cette section décrit les problèmes courants lors de la mise en place des plans d’agent.

Ces problèmes surviennent parfois lors de l’enregistrement :

• Erreur d’autorisation insuffisante
• Authentification manquante Azure CLI
• La ressource existe déjà
• Consentement administrateur non complété
• Fichiers de configuration manquants ou invalides
• L’installation est terminée mais les ressources ne sont pas créées
• Modèle d'agent non enregistré dans Entra
• Permissions API non accordées
• Identité gérée non activée
• La mise en place prend trop de temps ou se bloque

Erreur d’autorisation insuffisante

Symptôme: Erreur d’autorisation insuffisante lors de a365 setup l’exécution de la commande .

Vous devez avoir l’un des rôles suivants dans votre tenant Microsoft Entra :

• Administrateur général
• Administrateur d'identifiant d'agent
• Développeur d'identifiant d'agent

Et l'accès contributeur ou propriétaire de l’abonnement Azure.

Solution : Vérifiez que vous avez les autorisations requises à Entra.

• Accédez à : Microsoft Entra centre d’administration> Votre profil > rôles attribués
• Vérifier l’accès à l’abonnement Azure à l’aide de la commande PowerShell az account show

Authentification Azure CLI manquante

Symptôme: La configuration échoue avec des erreurs d’authentification.

Solution : Vérifiez que vous êtes connecté à Azure et vérifiez votre compte et votre abonnement.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

La ressource existe déjà

Symptôme: La configuration échoue avec une Resource already exists erreur pour le groupe de ressources, le plan de service d’applications ou l’application Web.

Solutions : Choisissez l’une des solutions suivantes

• Utilisation des ressources existantes

  Si des ressources existent et que vous souhaitez les utiliser, assurez-vous qu’elles correspondent à votre configuration. Utilisez la az resource list commande PowerShell.

  az resource list --resource-group <your-resource-group>
  

• Supprimer les ressources en conflit

  Supprime le groupe de ressources ou renomme tes ressources dans a365.config.json et relance la configuration.

  Vous pouvez utiliser la az group delete commande Powershell pour supprimer un groupe de ressources.

  # WARNING: This command deletes all resources in it
  az group delete --name <your-resource-group>
  

• Utilisez la commande de nettoyage pour repartir à zéro

  Utilisez la cleanup commande pour supprimer toutes les ressources de l’Agent 365, puis la a365 setup all commande pour relancer la configuration.

  Avertissement

  Exécuter a365 cleanup est destructeur

  a365 cleanup
  a365 setup all
  

Consentement administrateur non complété

Symptôme: Les fenêtres du navigateur s’ouvrent pendant la configuration mais vous les avez fermées sans avoir donné leur consentement.

Solution : Lance la a365 setup all commande. Le CLI redemande le consentement de l’administrateur :

Complétez tous les flux de consentement dans les fenêtres du navigateur qui apparaissent.

Fichiers de configuration manquants ou invalides

Symptôme: La configuration échoue avec « Configuration non trouvée » ou des erreurs de validation.

Solution:

1. Vérifiez que le a365.config.json fichier existe.
2. Afficher la configuration actuelle à l’aide de la commande d’affichage de configuration a365.
3. Si c’est manquant ou invalide, réinitialisez en utilisant la commande a365 config init.

# Verify a365.config.json exists
Test-Path a365.config.json

# Display current configuration
a365 config display

# If missing or invalid, re-initialize
a365 config init

L’installation est terminée mais les ressources ne sont pas créées

Symptom : la commande Setup réussit, mais Azure ressources n'existent pas.

Solution:

1. Vérifiez les ressources créées avec la a365 config display -g commande.
2. Vérifiez que les ressources Azure existent à l’aide de la commande az resource list.
3. Si des ressources manquent, vérifiez les erreurs dans la sortie de configuration et relancez la a365 setup all commande à nouveau.

# Check created resources
a365 config display -g

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

Modèle d'agent non enregistré dans Entra

Symptôme : Le programme d'installation se termine, mais ne trouve pas le modèle d'agent dans le centre d'administration Microsoft Entra.

Solution:

1. Obtenez l’ID du blueprint à partir de la configuration générée en utilisant la commande d’affichage -g de configuration a365.

   a365 config display -g
   # Look for: agentBlueprintId
   

2. Recherchez dans Microsoft Entra centre d’administration :

   1. Accédez à : Microsoft Entra centre d’administration.
   2. Accédez à App registrations>All applications
   3. Cherchez votre agentBlueprintId

3. Si elle n’est pas trouvée, relance la configuration avec la a365 setup all commande.

   a365 setup all
   

Permissions API non accordées

Symptôme: La configuration est terminée mais les autorisations apparaissent comme « Non accordées » dans Entra.

Solution:

1. Ouvrez Microsoft Entra centre d’administration

2. Trouvez l’inscription à votre application de plan directeur d’agent

3. Accéder aux autorisations d’API

4. Accorder le consentement de l’administrateur :

   1. Sélectionnez Accorder le consentement administrateur pour [Votre locataire]
   2. Confirmez l’action

5. Vérifiez que toutes les permissions affichent des coches vertes

Identité gérée non activée

Symptôme: L’application Web existe mais l’identité gérée n’est pas activée.

Solution:

1. Vérifiez le statut de l’identité gérée avec la az webapp identity show commande.
2. Si ce n’est pas activé, activez-le manuellement avec la az webapp identity assign commande.
3. Vérifiez qu’elle est activée avec la az webapp identity show commande.

# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

La mise en place prend trop de temps ou se bloque

Symptôme: La commande de configuration dure plus de 10 minutes sans être terminée.

Solution:

1. Vérifiez si les fenêtres du navigateur attendent le consentement – complétez tous les flux de consentement.

2. Si c'est vraiment bloqué, annulez (Ctrl+C) et vérifiez ce qui a été créé :

   # Check generated config
   a365 config display -g
   
   # Check Azure resources
   az resource list --resource-group <your-resource-group>
   

3. Nettoyez et réessayez :

   a365 cleanup
   a365 setup all