Configurer le blueprint de l’assistant

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

Note

La configuration d’un blueprint d’assistant est requise pour activer les fonctionnalités Inscription, Work IQ et Coéquipier IA. Voir Guide de démarrage du développement Agent 365 pour comprendre quelles fonctionnalités s’appliquent à votre assistant.

Pour plus d’informations sur l’identité Agent 365, voir Identité Agent 365.

Configuration requise

Avant de commencer, vérifiez que les prérequis suivants sont remplis :

  1. CLI Agent 365 : voir Installation de la CLI Agent 365.

  2. Autorisations nécessaires :

    • Utilisateur locataire valide avec l’un des rôles suivants :
      • Administrateur général
      • Développeur d’identifiant d’assistant
    • Avoir un accès à un abonnement Azure avec des autorisations adéquates pour créer des ressources

    Astuce

    Les assistants (pas les coéquipiers IA) n’ont pas besoin de fichier de configuration. Utilisez a365 setup all --agent-name <name> et la CLI identifie automatiquement votre locataire et votre application client. La configuration des coéquipiers IA nécessite un fichier a365.config.json.

Créer le blueprint de l’assistant

Utilisez la commande a365 setup pour créer des ressources Azure et enregistrer le blueprint de votre assistant. 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 assistant dans Azure.

Exécuter le programme d’installation

Exécutez la commande de configuration :

a365 setup -h

La commande offre plusieurs options. Vous pouvez effectuer l’ensemble de la configuration en une seule commande en utilisant a365 setup all ou choisir des options plus détaillées.

Note

a365 setup all Par défaut, il est en mode assistant de blueprint. Pour configurer un assistant coéquipier IA à la place, transmettez --aiteammate. Pour les assistants M365 (Teams, Copilot), transmettez également --m365 pour enregistrer automatiquement le point de terminaison de messagerie.

Configuration de l’assistant (par défaut) :

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

Configuration de l’assistant M365 (Teams/Copilot) :

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

Configuration des coéquipiers IA :

a365 setup all --aiteammate

Le processus d’installation entier effectue ces opérations :

  1. Crée une infrastructure Azure (si elle n’existe pas encore) :

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

  2. Enregistre le blueprint de l’assistant :

    • Crée le blueprint de l’assistant dans votre client Microsoft Entra
    • Crée des inscriptions d’application Microsoft Entra
    • Configure l’identité de l’assistant avec les autorisations requises
    • Définit managerApplications sur le blueprint, ce qui est nécessaire à la gestion de la plateforme

    Important

    Les blueprints doivent avoir managerApplications défini pour être acceptés par la plateforme. La CLI le définit automatiquement. Si vous avez un blueprint existant créé avant l’introduction de cette exigence, supprimez-le et exécutez a365 setup all à nouveau, ou modifiez-le manuellement via l’API Graph.

  3. Configure les autorisations API :

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

  4. Met à jour les fichiers config :

    • Enregistre 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

Note

La configuration prend généralement 3 à 5 minutes et enregistre automatiquement les paramètres dans a365.generated.config.json. Si vous exécutez en tant qu’administrateur général, le CLI peut ouvrir une fenêtre de navigateur pour le consentement administrateur – suivez le processus de consentement pour continuer. Si vous l’utilisez en tant que développeur ID d’assistant, aucune fenêtre de navigateur n’apparaît ; la CLI génère des URL de consentement qu’un administrateur général peut compléter ultérieurement.

Configuration à l’aide du développeur d’ID d’assistant

Si vous exécutez en tant que développeur assistant ID (et non administrateur général), a365 setup all complète la plupart des étapes automatiquement, mais l’octroi des autorisations OAuth2 nécessite une étape distincte de la part d’un administrateur général.

Quelles étapes s’accomplissent automatiquement :

  • Infrastructure Azure (groupe de ressources, Plan App Service, app web)
  • Enregistrement du blueprint de l’assistant
  • Autorisations pouvant être héritées pour les instances d’assistant

Quelles étapes nécessitent un administrateur général :

  • Octrois d’autorisations déléguées OAuth2 (consentement AllPrincipals) pour Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API et Power Platform

Comment compléter la configuration en utilisant un compte non-administrateur :

Étape Qui Action
1 Développeur Exécutez a365 setup all. Le CLI effectue toutes les étapes réalisables et affiche les étapes suivantes, dont une URL de consentement à destination d’un administrateur général.
2 Développeur Partagez l’URL de consentement de la sortie CLI avec votre administrateur général.
3 Administrateur général Ouvrez l’URL de consentement dans un navigateur connecté en tant qu’administrateur général et accordez les autorisations demandées.

Exécution de la commande :

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

Partagez les prochaines étapes générées par la CLI avec votre administrateur général. Ils peuvent ouvrir le lien fourni ou l’URL de consentement pour compléter l’octroi des autorisations OAuth2.

Vérifier l’installation

Lorsque la configuration est terminée, un résumé s’affiche et montre toutes les étapes accomplies. Vérifiez les ressources créées :

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

    Ouvrez a365.generated.config.json dans votre répertoire de travail. Ou utilisez PowerShell :

    Get-Content a365.generated.config.json | ConvertFrom-Json

    La sortie 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",
"messagingEndpoint": "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 :

    Champ Objectif À vérifier
    managedIdentityPrincipalId Authentification des identités gérée par Azure Doit être un GUID valide
    agentBlueprintId L’identifiant unique de votre assistant Utilisé dans le portail développeur et le Centre d’administration
    agentBlueprintObjectId Microsoft Entra ID de Blueprint
    messagingEndpoint Acheminement de messages Où Teams/Outlook envoient des messages à votre assistant
    agentBlueprintClientSecret Secret d’authentification Devrait exister (la valeur est masquée)
    resourceConsents Autorisations des API Devrait contenir des ressources telles que Microsoft Graph, outils Agent 365, API du bot de messagerie, API d’observabilité
    completed Statut de configuration Doit être true

    Note

    Si vous avez effectué la configuration en tant qu’administrateur d’ID d’assistant ou développeur ID d’assistant, resourceConsents peut rester vide et completed peut être false tant qu’un administrateur général n’a pas finalisé l’octroi des autorisations OAuth2 en utilisant les prochaines étapes affichées par la CLI.

  2. Vérifier les ressources Azure dans le portail Azure :

    Ou utiliser la commande PowerShell az resource list.

    # 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 :

      • Accédez à Groupes de ressources> Sélectionnez 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é>Affecté 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érifiez les applications Microsoft Entra dans le portail Azure :

    Accédez à Azure Active Directory>Inscriptions d’applications>Toutes les applications :

    • Recherchez le blueprint de votre assistant à l’aide de 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é pour [Votre locataire] »

  4. Vérifiez la présence du fichier de configuration généré :

    Vous devriez avoir un fichier nommé a365.generated.config.json contenant toutes les données de configuration.

    Utilisez la commande PowerShell Test-Path pour vérifier si le fichier existe.

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

    Important

    Enregistrez les deux fichiers a365.config.json et a365.generated.config.json. Vous aurez besoin de ces valeurs pour le déploiement et le dépannage.

  5. Vérifiez que le Web App a l’identité gérée activée :

    Utilisez la commande az webapp identity show 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>

    Prévu :

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

  6. Vérifier le Blueprint de l’assistant non inscrit dans Microsoft Entra :

    Dans le centre d’administration Microsoft Entra, recherchez votre agentBlueprintId ou effectuez une recherche par nom.

    Vérifiez que :

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

Pour en savoir plus, consultez :

Autorisations d’agent

Avant que les applications et les assistants puissent lire ou écrire des données Microsoft 365 (utilisateurs, e-mails, fichiers, Teams, assistants, etc.), vous devez explicitement leur accorder des autorisations Microsoft Graph. Les autorisations Microsoft Graph sont le modèle d’autorisation qui détermine les données et les actions auxquelles une application ou un service peut accéder par le biais des API Microsoft Graph à travers Microsoft 365 et Microsoft Entra ID.

En savoir plus : vue d’ensemble des autorisations Microsoft Graph

Pour utiliser les permissions Graph pour les instances d’assistant Agent 365, le développeur doit les déclarer dans le blueprint de l’assistant. Lorsqu’un administrateur active le blueprint dans le Centre d’administration Microsoft 365, le portail vérifie les permissions Graph du blueprint et incite l’administrateur à y consentir.

Pour comprendre et valider l’impact des permissions Graph sur le fonctionnement de votre assistant, vous pouvez :

Appliquez des permissions à votre blueprint

Utilisez a365 setup permissions custom pour appliquer des permissions API personnalisées directement dans votre blueprint dans Microsoft Entra.

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

Pour plus de détails sur la configuration et la suppression des permissions personnalisées, voir setup permissions custom.

Étapes suivantes

Déployez le code de votre assistant dans le cloud :

Microsoft Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Publier un assistant dans le centre d’administration Microsoft

Résolution des problèmes

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

Astuce

Le Guide de dépannage Agent 365 contient des recommandations générales de dépannage, les meilleures pratiques et des liens vers du contenu de dépannage pour chaque étape du cycle de développement de l’Agent 365.

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

Erreur d’autorisations insuffisantes

Symptôme : erreur de permissions insuffisantes lors de a365 setup l’exécution de la commande.

Vous avez besoin de l’un des rôles suivants dans votre utilisateur locataire Microsoft Entra :

  • Administrateur général
  • Développeur d’identifiant d’assistant

Accès contributeur ou propriétaire à l’abonnement Azure.

Solution : vérifiez que vous avez les autorisations requises dans Microsoft Entra.

Note

Si vous avez le rôle d’administrateur d’ID d’assistant ou de développeur d’ID d’assistant (et non d’administrateur général), a365 setup all fonctionne toujours mais ignore l’octroi des autorisations OAuth2. Une fois la configuration terminée, la CLI imprime les étapes suivantes pour qu’un administrateur général puisse compléter les subventions restantes. Ce workflow est prévu pour les organisations où le développeur d’assistant et l’administrateur général sont des personnes différentes.

Authentification Azure CLI manquante

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

Solution : assurez-vous d’être 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 erreur Resource already exists pour le groupe de ressources, le plan App Service ou l’application web.

Solutions : choisissez l’une des solutions suivantes.

  • Utiliser des ressources existantes

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

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

  • Supprimer les ressources en conflit

    Supprimez le groupe de ressources ou renommez vos ressources dans a365.config.json et relancez la configuration.

    Utilisez la commande PowerShell az group delete 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 cleanupcommande pour supprimer toutes les ressources Agent 365, puis la a365 setup allcommande pour relancer la configuration.

    Avertissement

    Exécuter a365 cleanup est destructeur.

    a365 cleanup
a365 setup all

Symptôme : vous avez ouvert des fenêtres de navigateur lors de la configuration mais les avez fermées sans avoir terminé la procédure de consentement, ou la configuration s’est terminée mais les autorisations OAuth2 sont toujours en attente.

Solution : choisissez en fonction de votre rôle :

  • Administrateur général : réexécutez a365 setup all. La CLI demande le consentement d’administrateur. Complétez le flux de consentement dans la fenêtre du navigateur qui apparaît.

  • Administrateur ou développeur d’ID d’assistant : vous ne pouvez pas compléter directement les subventions OAuth2. Exécutez a365 setup all — le récapitulatif de la configuration affiche les prochaines étapes pour un administrateur général, y compris un lien direct ou une URL de consentement pour finaliser l’octroi des autorisations. Partagez ces détails avec votre administrateur général.

Fichiers de configuration non valides ou manquants

Symptôme : l’installation échoue avec « Configuration introuvable » ou des erreurs de validation.

Solution :

  1. Vérifiez que le fichier a365.config.json existe déjà.
  2. S’il est manquant ou invalide, créez-le manuellement ou utilisez a365 setup all --agent-name <name> (assistants uniquement).
# Verify a365.config.json exists
Test-Path a365.config.json

La configuration s’est terminée mais les ressources n’ont pas été créées

Symptôme : la commande de configuration réussit, mais les ressources Azure n’existent pas.

Solution :

  1. Vérifiez les ressources créées en ouvrant a365.generated.config.json dans votre répertoire de travail.
  2. Vérifiez que les ressources Azure existent en utilisant la commande az resource list.
  3. Si des ressources sont manquantes, vérifiez les erreurs dans la sortie de la configuration et relancez la configuration en utilisant la commande a365 setup all.
# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# 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

Blueprint de l’assistant non inscrit dans Microsoft Entra

Symptôme : le programme d’installation se termine, mais vous ne trouvez pas le modèle de l’assistant dans le centre d’administration Microsoft Entra.

Solution :

  1. Obtenir un blueprint par ID dans a365.generated.config.json.

    Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId

  2. Recherchez dans le centre d’administration Microsoft Entra :

    1. Accédez au : centre d’administration Microsoft Entra.
    2. Accédez aux Enregistrements d’applications>Toutes les applications.
    3. Recherchez votre agentBlueprintId.

  3. Si vous ne le trouvez pas, relancez la configuration en utilisant la commande a365 setup all.

    a365 setup all

Permissions d’API non accordées

Symptôme : la configuration est terminée mais les autorisations s’affichent comme « Non accordées » dans Microsoft Entra.

Solution :

  1. Ouvrez le centre d’administration Microsoft Entra.

  2. Trouvez l’inscription à votre application du blueprint d’assistant.

  3. Accédez à Autorisations API.

  4. Accorder un consentement d’administrateur :

    1. Sélectionnez Accorder un consentement à [votre locataire].
    2. Confirmez l’action.

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

Identité managé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 en utilisant la commande az webapp identity show.
  2. Si l’identité gérée n’est pas activée, activez-la manuellement en utilisant la commande az webapp identity assign.
  3. Vérifiez qu’elle est activée en utilisant la commande az webapp identity show.
# 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>

L’installation prend trop de temps ou cesse de répondre

Symptôme : la commande de configuration s’exécute pendant plus de 10 minutes sans se terminer.

Solution :

  1. Si vous êtes administrateur général, vérifiez si une fenêtre de navigateur attend le consentement d’un administrateur. Complétez le processus de consentement pour débloquer la configuration.

  2. Si la configuration ne répond vraiment plus, annulez-la (Ctrl+C) et vérifiez ce qui a été créé.

    # Check generated config
Get-Content a365.generated.config.json | ConvertFrom-Json

# Check Azure resources
az resource list --resource-group <your-resource-group>

  3. Nettoyez et réessayez.

    a365 cleanup
a365 setup all

Nettoyez un assistant sans configuration

Symptôme : vous avez approvisionné un assistant avec a365 setup all --agent-name <name> et souhaitez maintenant le supprimer, mais vous ne disposez pas du fichier a365.config.json.

Solution : utiliser a365 cleanup --agent-name pour supprimer l’assistant sans fichier de configuration. La CLI lit les identifiants de ressources à partir de la configuration globale générée qui a été écrite lors de l’initialisation (bootstrap).

a365 cleanup --agent-name <your-agent-name>

Astuce

Si la commande bloque lors de l’authentification, elle bascule automatiquement vers le mode d’authentification par code d’appareil. Suivez les instructions affichées dans le terminal pour finaliser l’authentification.

Si vous n’avez plus la configuration générée globalement (par exemple, après avoir réinstallé la ligne de commande), utilisez a365 cleanup avec un a365.config.json minimal créé manuellement, ou supprimez directement les ressources via le portail Azure et le centre d’administration Microsoft Entra.

Impossible d’envoyer le premier message dans Teams

Symptôme : après l’approvisionnement d’une instance d’assistant, il ne peut pas envoyer de message au gestionnaire d’assistants comme message de bienvenue.

Solution : la permission [Chat.Create][perm-chatcreate] est nécessaire pour créer un objet de conversation instantanée. Si une conversation individuelle existe déjà, cette opération renvoie la conversation existante et n’en crée pas d’autre.

  • Last updated on