Schéma de configuration de l’agent

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.

Prerequisites

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
     • Développeur Agent ID
   • Accès à un abonnement Azure avec des autorisations pour créer des ressources

   Conseil

   Les agents (et non les collègues d’IA) n’ont pas besoin d’un fichier de configuration. Utiliser a365 setup all --agent-name <name> et l’interface CLI résout automatiquement votre client et votre application cliente. La configuration d’un coéquipier IA nécessite une création manuelle a365.config.json.

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.

Configuration de l’agent (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’agent M365 (Teams/Copilot) :

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

Configuration d’un coéquipier d’intelligence artificielle :

a365 setup all --aiteammate

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 blueprint de l’agent dans votre client Microsoft Entra
   • Crée des enregistrements d'applications Microsoft Entra
   • Configure l’identité de l’assistant avec les autorisations requises
   • Définit managerApplications sur le blueprint, ce qui est requis pour la facilité de gestion de la plateforme

   Important

   Les blueprints doivent être managerApplications configurés pour être acceptés par le système. L’interface CLI définit cette valeur automatiquement. Si vous avez créé un blueprint existant avant l’introduction de cette exigence, supprimez-le et réexécutez-le a365 setup all, ou corrigez-le manuellement via le API Graph.

3. Configure les autorisations API :

   • Définir les étendues de Microsoft API Graph
   • 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

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

Si vous exécutez en tant que développeur d’ID d’agent (et non administrateur général), a365 setup all effectue la plupart des étapes automatiquement, mais les octrois d’autorisations OAuth2 nécessitent une étape d’administrateur général distincte.

Quelles sont les étapes effectuées automatiquement :

• Infrastructure Azure (groupe de ressources, plan App Service, application web)
• Enregistrement du blueprint de l’assistant
• Autorisations héritables pour les instances d'agents

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

• Octrois d’autorisations déléguées OAuth2 (consentement AllPrincipals) pour Microsoft Graph, les outils Agent 365, l'API de bot de messagerie, l'API d'observabilité et l'API Power Platform

Comment effectuer la configuration à l’aide d’un compte non administrateur :

Exécution des commandes :

# 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 étapes suivantes imprimées par l’interface CLI avec votre administrateur général. Ils peuvent ouvrir le lien de consentement ou l'URL fournie pour terminer les autorisations OAuth2.

Vérifier l’installation

Une fois l’installation terminée, vous voyez un résumé qui affiche toutes les étapes terminées. Vérifiez les ressources créées :

1. Vérifier 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 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",
   "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	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	Microsoft Entra ID de Blueprint
   messagingEndpoint	Acheminement 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

   Note

   Si vous avez exécuté le programme d’installation en tant qu'Administrateur ID d'Agent ou Développeur ID d'Agent, resourceConsents peut être vide et completed peut être false jusqu’à ce qu’un administrateur global termine les autorisations OAuth2 en suivant les étapes suivantes affichées par le CLI.

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

   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érifiez les applications Microsoft Entra dans Portail Azure :

   Accédez à Azure Active Directory>inscriptions d'applications>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éé :

   Vous devez avoir un fichier nommé a365.generated.config.json qui contient toutes les données de configuration.

   Utilisez la commande PowerShell Test-Path pour vérifier qu’elle existe.

   # 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 que le blueprint de l'agent est enregistré dans Microsoft Entra :

   Dans le Centre d’administration Microsoft Entra, 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 d’application client personnalisée

Autorisations d’agent

Avant que les applications et les agents puissent lire ou écrire des données Microsoft 365 (utilisateurs, courrier, fichiers, Teams, agents, et ainsi de suite), vous devez leur accorder explicitement des autorisations Microsoft Graph. Les autorisations Microsoft Graph sont le modèle d’autorisation qui contrôle les données et actions auxquelles une application ou un service peut accéder via les API Microsoft Graph sur Microsoft 365 et l’ID Microsoft Entra.

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

Pour utiliser les autorisations Graph pour les instances de l’agent 365, le développeur doit les déclarer dans le blueprint de l’agent. Lorsqu’un administrateur active le blueprint dans le Centre d’administration Microsoft 365, le portail passe en revue les autorisations Graph du blueprint et invite l’administrateur à lui donner son consentement.

Pour comprendre et valider la façon dont les autorisations Graph activent votre agent, vous pouvez :

• Affichez toutes les autorisations Graph disponibles.
• Visitez l’Explorateur Graph pour essayer des requêtes, inspecter les réponses et comprendre les autorisations.
• Utilisez Microsoft 365 Agents Playground pour tester votre agent localement avant le déploiement.

Appliquer des autorisations à votre blueprint

Utilisez a365 setup permissions custom pour appliquer des autorisations d’API personnalisées inline à 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 d’informations sur la configuration et la suppression d’autorisations personnalisées, consultez setup permissions custom.

Étapes suivantes

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

Dépannage

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

Ces problèmes se produisent parfois lors de l’inscription :

• Erreur d’autorisation insuffisante
• Authentification Azure CLI manquante
• 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 inscrit dans Microsoft Entra
• Permissions API non accordées
• Identité gérée non activée
• L’installation prend trop de temps ou cesse de répondre
• Nettoyer un agent sans configuration
• Impossible d’envoyer le premier message dans Teams

Erreur d’autorisation insuffisante

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

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

• Administrateur général
• Développeur Agent ID

Et un accès en tant que contributeur ou propriétaire à l'abonnement Azure.

Solution: Vérifiez que vous disposez des autorisations requises dans Microsoft Entra.

• Accédez à : centre d’administration Microsoft Entra> Votre profil > rôles attribués
• Vérifiez 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: Le programme d’installation échoue avec Resource already exists une erreur pour le groupe de ressources, le plan App Service 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

  Supprimez le groupe de ressources ou renommez vos ressources dans a365.config.json et réexécutez la configuration.

  Utilisez 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 Agent 365, puis utilisez la commande pour réexécuter le a365 setup all programme d’installation.

  Avertissement

  L’exécution a365 cleanup est destructrice.

  a365 cleanup
  a365 setup all
  

Consentement administrateur non complété

Symptôme: Vous avez ouvert des fenêtres de navigateur pendant l’installation, mais les avez fermées sans avoir terminé le consentement, ou l’installation terminée, mais les octrois d’autorisations OAuth2 sont toujours en attente.

Solution: Choisissez en fonction de votre rôle :

• Administrateur général : réexécutez a365 setup all . L’interface CLI demande le consentement de l’administrateur. Terminez le flux de consentement dans la fenêtre du navigateur qui s’affiche.

• Administrateur d’ID d’agent ou développeur : vous ne pouvez pas effectuer les autorisations OAuth2 directement. Exécuter a365 setup all : le résumé de l’installation imprime les étapes suivantes pour un administrateur global, y compris un lien direct ou une URL de consentement pour compléter les autorisations. Partagez ces détails avec votre administrateur général.

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. En cas d’absence ou non valide, créez-le manuellement ou utilisez a365 setup all --agent-name <name> (agents uniquement).

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

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 en ouvrant a365.generated.config.json dans votre répertoire de travail.
2. Vérifiez que les ressources Azure existent à l’aide de la commande az resource list.
3. Si des ressources sont manquantes, recherchez les erreurs dans la sortie de l’installation et réexécutez le programme d’installation à l’aide de la a365 setup all commande.

# 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

Plan de l’agent non enregistré dans Microsoft Entra

Symptom : Le programme d'installation se termine, mais vous ne trouvez pas le blueprint de l'agent dans centre d’administration Microsoft Entra.

Solution:

1. Obtenir l’ID de blueprint à partir de a365.generated.config.json.

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

2. Recherchez dans centre d’administration Microsoft Entra :

   1. Accédez à : centre d’administration Microsoft Entra.
   2. Accédez aux enregistrements d'applications>Toutes les applications.
   3. Cherchez votre agentBlueprintId.

3. S’il est introuvable, réexécutez le programme d’installation à l’aide de la a365 setup all commande.

   a365 setup all
   

Permissions API non accordées

Symptôme: Le programme d’installation se termine, mais les autorisations s’affichent comme « Non accordées » dans Microsoft Entra.

Solution:

1. Ouvrez centre d’administration Microsoft Entra.

2. Recherchez l’inscription de l’application blueprint de votre agent.

3. Accédez à Autorisations 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 autorisations affichent les coches vertes.

Identité gérée non activée

Symptôme: L’application web existe, mais l’identité managée n’est pas activée.

Solution:

1. Vérifiez l’état de l’identité managée à l’aide de la az webapp identity show commande.
2. Si cette option n’est pas activée, activez-la manuellement à l’aide de la az webapp identity assign commande.
3. Vérifiez qu’elle est activée à l’aide de 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>

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

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

Solution:

1. Si vous exécutez en tant qu’administrateur général, vérifiez si une fenêtre de navigateur attend le consentement de l’administrateur. Terminez le flux de consentement pour débloquer la configuration.

2. Si le programme d’installation ne répond vraiment plus, annulez l'opération (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. Nettoyer et réessayer.

   a365 cleanup
   a365 setup all
   

Nettoyer un agent sans configuration

Symptôme: Vous avez provisionné un agent avec a365 setup all --agent-name <name> lequel vous souhaitez maintenant le supprimer, mais vous n’avez pas de a365.config.json fichier.

Solution: Permet a365 cleanup --agent-name de supprimer l’agent sans fichier de configuration. L’interface CLI lit les ID de ressource à partir de la configuration générée globale qui a été écrite lors de l’installation de bootstrap.

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

Si vous n’avez plus la configuration générée globale (par exemple, après la réinstallation du CLI), utilisez a365 cleanup avec une a365.config.json minimale créée manuellement, ou supprimez directement des ressources via Portail Azure et centre d’administration Microsoft Entra.

Impossible d’envoyer le premier message dans Teams

Symptôme: Après l’approvisionnement d’une instance d’agent, il ne peut pas envoyer de message au gestionnaire d’agents comme message d’accueil.

Solution: L’autorisation [Chat.Create][perm-chatcreate] est requise pour créer un objet de conversation. Si une conversation en un-à-un existe déjà, cette opération retourne la conversation existante et n’en crée pas une nouvelle.

• Pour implémenter, configurez les autorisations héritées de votre blueprint pour inclure l’étendueChat.Create.
• Configurez un message de conversation Teams pour qu’il envoie une fois qu’une instance d’agent est provisionnée.
• Créez une instance d’agent à partir du blueprint et testez le message de première exécution.