Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Informations de référence sur la commande CLI
Configurez votre environnement Agent 365 avec un contrôle granulaire sur chaque étape. Cette commande gère le flux de travail d’installation initial pour les blueprints Agent 365.
rôle Minimum requis : Azure Contributeur + Agent ID Developer
Note
Le rôle que vous maintenez détermine la quantité de l’installation terminée dans une seule exécution. L’administrateur général peut effectuer toutes les étapes en même temps. L’administrateur de l’identifiant d’agent et le développeur de l’identifiant d’agent peuvent accomplir toutes les étapes sauf les accords d’autorisation OAuth2 (consentement administrateur), qui nécessitent une action d’un administrateur global. Une fois la configuration terminée, la CLI affiche directement les étapes suivantes pour l’administrateur global dans la sortie.
Syntax
a365 setup [command] [options]
Options
| Option | Description |
|---|---|
-?, , -h--help |
Affichez les informations d’aide et d’utilisation. |
Ordre d’exécution recommandé
# 0. Check prerequisites (optional)
a365 setup requirements
# 1. Create blueprint
a365 setup blueprint
# 2. Configure MCP permissions
a365 setup permissions mcp
# 3. Configure bot permissions
a365 setup permissions bot
# 4. Configure CopilotStudio permissions (if needed)
a365 setup permissions copilotstudio
# 5. Configure custom permissions (if needed)
a365 setup permissions custom
Ou exécutez toutes les étapes en même temps :
# Full setup using config file (a365.config.json)
a365 setup all
# Config-free: no a365.config.json needed
a365 setup all --agent-name "MyAgent"
Si vous exécutez en tant qu’administrateur d’ID d’agent ou développeur d’ID d’agent (et non administrateur général), a365 setup all effectue toutes les étapes à l’exception des octrois d’autorisations OAuth2. Une fois terminé, le résultat inclut les étapes suivantes pour qu’un administrateur global complète les subventions — y compris un lien direct ou une URL de consentement qu’ils peuvent ouvrir.
setup requirements
Valider les prérequis pour la configuration de l’agent 365. Exécute des vérifications des exigences modulaires et fournit des conseils pour tous les problèmes qu’il trouve.
a365 setup requirements [options]
Cette commande exécute les étapes suivantes :
- Vérifie toutes les conditions préalables requises pour la configuration de l’agent 365.
- Signale les problèmes liés aux conseils de résolution détaillés.
- Continue à vérifier toutes les exigences, même si certaines vérifications échouent.
- Fournit un résumé de toutes les vérifications à la fin.
Tip
Si vous êtes administrateur global et que l’application cliente bien connue Agent 365 CLI n’est pas disponible dans votre locataire, setup requirements cela vous invite à la créer automatiquement. Saisissez un identifiant ou un formulaire C d’application existant pour créer l’application et accordez le consentement administrateur en une seule étape – pas besoin d’inscription manuelle sur Entra.
Options requirements
| Option | Description |
|---|---|
-v, --verbose |
Activez la journalisation détaillée. |
--category <category> |
Effectuez des vérifications pour une catégorie spécifique uniquement, telles que Azure, Authentication, PowerShell ou Tenant Enrollment. |
-?, , -h--help |
Affichez les informations d’aide et d’utilisation. |
Note
setup requirements Il ne nécessite pas de fichier de configuration - lance-le dans n’importe quel répertoire.
setup blueprint
Créer un blueprint d’agent (Entra ID inscription d’application).
Autorisations minimales requises : rôle développeur d’ID d’agent
a365 setup blueprint [options]
Options blueprint
| Option | Description |
|---|---|
-n, --agent-name <name> |
Nom de la base de l’agent. Quand vous proposez cette option, vous n’avez pas besoin de fichier de configuration. La commande détecte automatiquement l’identifiant du locataire depuis az account show. Écrasez-le par --tenant-id. |
--tenant-id <tenantId> |
ID de locataire Azure AD. Overrides auto-detection. Utiliser avec --agent-name. |
-v, --verbose |
Afficher une sortie détaillée. |
--dry-run |
Afficher ce que la commande ferait sans l’exécuter. |
--skip-requirements |
Ignorez la vérification de validation des exigences. Utilisez avec précaution. |
--no-endpoint |
N’inscrivez pas le point de terminaison de messagerie (blueprint uniquement). |
--endpoint-only |
Inscrivez uniquement le point de terminaison de messagerie. Nécessite un blueprint existant. |
--update-endpoint <url> |
Supprimez le point de terminaison de messagerie existant et enregistrez-en un nouveau avec l’URL spécifiée. |
--m365 |
Traitez cet agent comme un agent M365. Enregistre le point de terminaison de messagerie via la plateforme MCP. Par défaut, c’est false (adhésion volontaire). |
-?, , -h--help |
Affichez les informations d’aide et d’utilisation. |
setup permissions
Configurez les autorisations OAuth2 et les autorisations héritées.
Autorisations minimales requises : Administrateur général
a365 setup permissions [command] [options]
Options
| Option | Description |
|---|---|
-?, , -h--help |
Affichez les informations d’aide et d’utilisation. |
Subcommands
| Subcommand | Description |
|---|---|
mcp |
Configurez le serveur MCP OAuth2 accorde et hérite des autorisations. |
bot |
Configurez l’API de bot de messagerie OAuth2 accorde et hérite des autorisations. |
custom |
Applique des autorisations d’API personnalisées à votre blueprint d’agent qui dépassent les autorisations standard requises pour l’opération de l’agent. |
copilotstudio |
Configure les autorisations OAuth2 accorde et hérite des autorisations pour que le blueprint de l’agent appelle Copilot Studio copilotes via l’API Power Platform. |
setup permissions mcp
Configurez le serveur MCP OAuth2 accorde et hérite des autorisations.
Autorisations minimales requises : Administrateur général
a365 setup permissions mcp [options]
This command:
-
ToolingManifest.jsonLit à partir dudeploymentProjectPathfichier spécifié dansa365.config.json. - Accorde des autorisations déléguées OAuth2 pour chaque étendue de serveur MCP au blueprint de l’agent.
- Configure les autorisations héritées afin que les instances d’agent puissent accéder aux outils MCP.
- Est idempotent et sûr à exécuter plusieurs fois.
Important
- Avant d’exécuter cette commande, vérifiez que cela
deploymentProjectPathpointe vers le dossier projet contenant les fichiers .ToolingManifest.jsonSi le développeur ajoute des serveurs MCP sur un autre ordinateur, partagez d’abord la mise à jourToolingManifest.jsonavec l’administrateur général. L’exécution sans correctionToolingManifest.jsonn’ajoute pas les nouvelles autorisations de serveur MCP au blueprint. - Exécutez cette commande après l’exécution
a365 develop add-mcp-serversdu développeur . L’ajout de serveurs MCP au manifeste et l’octroi d’autorisations au blueprint sont deux étapes distinctes. Une fois cette commande terminée, les autorisations du serveur MCP sont visibles dans le blueprint de l’agent.
Options permissions mcp
| Option | Description |
|---|---|
-n, --agent-name <name> |
Nom de la base de l’agent. Quand vous proposez cette option, vous n’avez pas besoin de fichier de configuration. |
--tenant-id <tenantId> |
ID de locataire Azure AD. Overrides auto-detection. Utiliser avec --agent-name. |
-v, --verbose |
Afficher une sortie détaillée. |
--dry-run |
Afficher ce que la commande ferait sans l’exécuter. |
--remove-legacy-scopes |
Supprime les étendues partagées héritées (McpServers.*.All format) du blueprint après la migration vers des autorisations par serveur (Tools.ListInvoke.All). À utiliser seulement après la confirmation du SDK V2 en ligne - les agents sur le SDK V1 perdent l’accès à l’outil s’ils sont retirés prématurément. |
-?, , -h--help |
Affichez les informations d’aide et d’utilisation. |
Migrer vers des autorisations MCP par serveur
Utilisez cette option --remove-legacy-scopes lors de la migration du modèle d’autorisations partagées héritées vers des autorisations par serveur :
-
Modèle partagé hérité : ID d’application de ressource unique (
ea9ffc3e-8a23-4a7d-836d-234d7c7565c1) avec des étendues partagées telles queMcpServers.Mail.AlletMcpServers.Teams.All. -
Modèle par serveur : chaque serveur MCP a son propre ID d’application avec l’étendue
Tools.ListInvoke.All.
L’exemple suivant montre comment les autorisations par serveur apparaissent dans l’centre d’administration Microsoft Entra après l’application du blueprint. Chaque serveur MCP, tel que Work IQ Calendar MCP et Work IQ Mail MCP, a sa propre étendue déléguée Tools.ListInvoke.All . Une étendue partagée McpServersMetadata.Read.All fournit l’accès aux métadonnées du serveur MCP.
setup permissions bot
Configurez l’API de bot de messagerie OAuth2 accorde et hérite des autorisations.
Autorisations minimales requises : Administrateur général
Prérequis : Autorisations Blueprint et MCP (exécuter en a365 setup permissions mcp premier)
a365 setup permissions bot [options]
Options permissions bot
| Option | Description |
|---|---|
-n, --agent-name <name> |
Nom de la base de l’agent. Quand vous proposez cette option, vous n’avez pas besoin de fichier de configuration. |
--tenant-id <tenantId> |
ID de locataire Azure AD. Overrides auto-detection. Utiliser avec --agent-name. |
-v, --verbose |
Afficher une sortie détaillée. |
--dry-run |
Afficher ce que la commande ferait sans l’exécuter. |
-?, , -h--help |
Affichez les informations d’aide et d’utilisation. |
setup permissions custom
Applique des autorisations d’API personnalisées à votre blueprint d’agent qui dépassent les autorisations standard requises pour l’opération de l’agent. À l'aide de cette commande, vous accordez à votre agent l'accès à des étendues Microsoft Graph supplémentaires, telles que Présence, Fichiers et Conversation, ou aux API personnalisées inscrites dans le locataire Microsoft Entra ID de votre organisation.
Autorisations minimales requises : Administrateur général
Conditions préalables : Exécuter a365 setup blueprint en premier.
a365 setup permissions custom [options]
This command:
- Configure les octrois d’autorisations déléguées OAuth2 avec le consentement administrateur pour chaque ressource configurée.
- Définit des autorisations héritantes afin que les utilisateurs de l’agent puissent hériter de l’accès à partir du blueprint.
- Rapproche Microsoft Entra avec la configuration actuelle en ajoutant de nouvelles autorisations et en supprimant les autorisations que vous avez supprimées de la configuration.
- Est idempotent et sûr à exécuter plusieurs fois.
Options permissions custom
| Option | Description |
|---|---|
-n, --agent-name <name> |
Nom de la base de l’agent. Quand vous proposez cette option, vous n’avez pas besoin de fichier de configuration. |
--tenant-id <tenantId> |
ID de locataire Azure AD. Overrides auto-detection. Utiliser avec --agent-name. |
-v, --verbose |
Afficher une sortie détaillée. |
--dry-run |
Afficher ce que la commande ferait sans l’exécuter. |
--resource-app-id <guid> |
Identifiant d’application de ressource (GUID) pour une autorisation personnalisée en ligne. Utiliser avec --scopes. |
--scopes <scopes> |
Oscillations déléguées séparées par virgules pour la permission personnalisée en ligne. Utiliser avec --resource-app-id. |
-?, , -h--help |
Affichez les informations d’aide et d’utilisation. |
Configurez les permissions personnalisées en ligne
Utiliser --resource-app-id et --scopes appliquer directement les permissions personnalisées sans modification a365.config.json:
# Add Microsoft Graph extended permissions
a365 setup permissions custom `
--resource-app-id 00000003-0000-0000-c000-000000000000 `
--scopes Presence.ReadWrite,Files.Read.All,Chat.Read
# Add custom API permissions
a365 setup permissions custom `
--resource-app-id <your-api-app-id> `
--scopes CustomScope.Read,CustomScope.Write
Le nom de la ressource est résolu automatiquement depuis Microsoft Entra. Vous n’avez pas besoin de le préciser.
Configurez les permissions personnalisées via le fichier de configuration
Sinon, ajoutez customBlueprintPermissions à a365.config.json et exécutez la commande sans drapeaux en ligne :
a365 setup permissions custom
Cette commande réconcilie Microsoft Entra avec les permissions configurées – elle ajoute de nouvelles permissions et supprime toutes les permissions supprimées de la configuration.
Intégration à setup all
Lorsque votre configuration inclut des autorisations personnalisées, l’exécution a365 setup all les configure automatiquement dans le cadre d’une seule phase d’autorisation batch. L’ordre d’installation complet est le suivant :
- Blueprint
- Lot d’autorisations (MCP, API bot, autorisations de blueprint personnalisées , toutes configurées ensemble)
setup permissions copilotstudio
Configure les autorisations OAuth2 accorde et hérite des autorisations pour que le blueprint de l’agent appelle Copilot Studio copilotes via l’API Power Platform.
Autorisations minimales requises : Administrateur général
Conditions préalables : Exécuter a365 setup blueprint en premier.
a365 setup permissions copilotstudio [options]
This command:
- Vérifie que le principal du service d’API Power Platform existe dans votre locataire.
- Crée une autorisation OAuth2 à partir du blueprint vers l’API Power Platform avec l’étendue
CopilotStudio.Copilots.Invoke. - Définit des autorisations héritantes afin que les instances d’agent puissent appeler Copilot Studio copilotes.
Options permissions copilotstudio
| Option | Description |
|---|---|
-n, --agent-name <name> |
Nom de la base de l’agent. Quand vous proposez cette option, vous n’avez pas besoin de fichier de configuration. |
--tenant-id <tenantId> |
ID de locataire Azure AD. Overrides auto-detection. Utiliser avec --agent-name. |
-v, --verbose |
Afficher une sortie détaillée. |
--dry-run |
Afficher ce que la commande ferait sans l’exécuter. |
-?, , -h--help |
Affichez les informations d’aide et d’utilisation. |
Utilisez cette commande lorsque votre agent doit appeler Copilot Studio copilotes au moment de l’exécution ou appeler des API Power Platform qui nécessitent des autorisations CopilotStudio.
setup all
Effectuer toutes les étapes de configuration pour configurer votre environnement Agent 365
a365 setup all [options]
Exécute la configuration complète de l’agent 365, toutes les étapes en séquence.
Inclut : Blueprint et autorisations.
Les étapes qui se terminent dépendent de votre rôle :
| Step | Global Administrator | Administrateur d’ID d’agent | Développeur Agent ID |
|---|---|---|---|
| Prerequisites check | Yes | Yes | Yes |
| Création du blueprint de l’agent | Yes | Yes | Yes |
| Autorisations héréditaires (IA uniquement pour les coéquipiers) | Yes | Yes | Yes |
| Octrois d’autorisations OAuth2 (consentement administrateur) | Yes | Nécessite une étape en disponibilité générale | Nécessite une étape en disponibilité générale |
Octroi d’identité d’agent (--authmode s2s ou both) |
Yes | Yes | PowerShell fallback |
Lorsque vous exécutez a365 setup all sans administrateur général, l’interface CLI :
- Effectue toutes les étapes qu’il peut effectuer (création de blueprint et autorisations pouvant être héritées).
- Génère des URL de consentement par administrateur de ressources et les enregistre dans
a365.generated.config.json. - Affiche les étapes suivantes dans la sortie pour qu’un administrateur global complète les subventions OAuth2, incluant un lien direct ou une URL de consentement.
Tip
Si vous êtes administrateur général, a365 setup all effectue tout dans une seule exécution sans remise nécessaire.
Autorisations minimales requises :
- Rôle développeur d’ID d’agent (pour la création de blueprints)
- Global Administrator (pour les autorisations OAuth2 - si ce n’est pas disponible, la CLI affiche les étapes suivantes dans la sortie)
- Administrateur d’ID d’agent, administrateur d’application ou administrateur global (pour les accords d’identité d’agent S2S (Serveur-à-Serveur) -
--authmode s2souboth; si ce n’est pas disponible, la CLI affiche un plan de secours PowerShell dans le résumé de configuration)
Options setup all
| Option | Description |
|---|---|
-v, --verbose |
Afficher une sortie détaillée. |
--dry-run |
Afficher ce que la commande ferait sans l’exécuter. |
--skip-requirements |
Ignorez la vérification de validation des exigences. Utilisez la prudence : le programme d’installation peut échouer si les prérequis ne sont pas remplis. |
--aiteammate |
Utilisez ce paramètre pour orienter le flux d’agents de l’équipe IA afin de fournir uniquement des blueprint et des permissions. Sans ce paramètre, le flux d’agent blueprint crée automatiquement le principal de service d’identité de l’agent sans utilisateur Entra. Ce paramètre supprime le aiteammate champ dans a365.config.json. |
--authmode <mode> |
Motif d’authentification pour l’autorisation d’identité des agents (agents blueprint uniquement).
obo (par défaut) — subventions déléguées à portée de principal, aucun rôle administratif nécessaire.
s2s — assignations de rôles d’application sur le SP d’identité d’agent, nécessite Administrateur d’ID d’Agent, Administrateur d’Application ou Administrateur Global ; Solution de secours PowerShell s’affiche si le rôle est absent.
both — applique les subventions OBO (On-Behalf-Of) et S2S. Non pris en charge par --aiteammate. Peut aussi être défini comme authMode dans a365.config.json. |
--agent-registration-only |
Sauter les étapes de blueprint et d’autorisations et ne lance que l’enregistrement de l’agent. Permet de réessayer une étape d’inscription ayant échoué. |
--m365 |
Traitez cet agent comme un agent M365. Enregistre le point de terminaison de messagerie via la plateforme MCP. Par défaut, c’est false (adhésion volontaire). |
-n, --agent-name <name> |
Nom de base de l’agent (par exemple, "MyAgent"). Lorsqu’il est fourni, aucun fichier de configuration n’est requis. Dérive les noms d’affichage en tant que "<name> Identity" et "<name> Blueprint". TenantId est détecté automatiquement à partir az account show de (remplacer par --tenant-id). ClientAppId est résolu en recherchant Agent 365 CLI dans votre locataire. |
--tenant-id <tenantId> |
ID de locataire Azure AD. Remplace la détection automatique à partir de az account show. Utilisez-le --agent-name lors de l’exécution dans un environnement non interactif ou pour cibler un locataire spécifique. |
-?, , -h--help |
Affichez les informations d’aide et d’utilisation. |
Agent setup
Par défaut, il a365 setup all exécute le flux d’agent blueprint. Ce flux crée un agent sans dépendance Dataverse ou IA. Cela fonctionne pour les agents qui communiquent directement avec la plateforme Agent 365.
# Default: uses a365.config.json
a365 setup all
# Or explicitly (same result)
a365 setup all --aiteammate false
Pour exécuter le flux d’agents coéquipiers IA à la place, passez --aiteammate.
Ce flux effectue les étapes suivantes dans la séquence :
- validation Requirements : vérifie les rôles et les prérequis Azure.
- Création de l’empreinte bleue — crée ou réutilise l’application Blueprint de l’agent Entra ID.
- autorisations Batch : configure les octrois d’autorisations déléguées sur le blueprint pour Microsoft Graph, les outils Agent 365, l’API de bot de messagerie, l’API Observabilité, Power Platform et toutes les ressources personnalisées.
- Création d’identitéAgent : crée une identité d’agent dans Entra ID via le API Graph d’identité de l’agent.
- Inscription de l’agent : inscrit l’agent via l’API d’inscription de l’agent AgentX V2.
-
Synchronisation de la configuration : écrit les paramètres de connexion du runtime et la configuration de l’observabilité dans vos fichiers projet (
appsettings.json,.env).
Note
La configuration de l’agent nécessite six autorisations d’API bêta supplémentaires sur votre application cliente personnalisée : AgentIdentityBlueprint.AddRemoveCreds.All, , AgentIdentityBlueprint.DeleteRestore.AllAgentInstance.ReadWrite.All, AgentIdentity.ReadWrite.All, , AgentIdentity.Create.Allet AgentIdentity.DeleteRestore.All. Consultez l’inscription d’application cliente personnalisée pour obtenir la liste complète.
Configuration sans configuration avec --agent-name
Si vous n’avez pas de a365.config.json fichier, utilisez cette option --agent-name pour exécuter le programme d’installation sans un fichier. L’interface CLI détecte automatiquement votre locataire et résout l’application cliente en recherchant l’inscription d’application connue Agent 365 CLI dans votre locataire.
# Preview what would happen (no changes made)
a365 setup all --agent-name "MyAgent" --dry-run
# Run the full setup
a365 setup all --agent-name "MyAgent"
Lors de l’utilisation de --agent-name:
-
TenantId est détecté automatiquement à partir de
az account show.--tenant-idPassez à remplacer. -
ClientAppId est résolu en recherchant une application Entra nommée
Agent 365 CLIdans votre locataire. S’il n’est pas trouvé, l’interface CLI se termine par une erreur. Consultez l’inscription d’application cliente personnalisée pour savoir comment inscrire cette application. -
Les noms d’affichage sont dérivés comme
"<name> Agent"(identité) et"<name> Blueprint"(blueprint). - L’infrastructure est toujours ignorée (l’hébergement externe est supposé).
-
La synchronisation de configuration (écriture
appsettings.json) est ignorée, car aucun chemin de projet n’est configuré.
Consentement de l’administrateur lors de l’installation
Si votre application cliente ne dispose AllPrincipals pas du consentement administrateur pour les autorisations requises, l’interface CLI détecte ceci et vous invite à accorder le consentement de manière interactive :
The following permissions require admin consent:
AgentIdentity.ReadWrite.All
AgentIdentity.Create.All
...
Grant admin consent for these permissions now? [y/N]:
Entrez y pour accorder le consentement en ligne. Si vous n’êtes pas un administrateur global, refusez — la CLI affiche les étapes suivantes pour un administrateur global dans le résumé de configuration.
Attributions d’identité d’agent (--authmode)
Par défaut, a365 setup all crée des concessions déléguées à portée principale sur le principal de service d’identité de l’agent (obo mode). Ces subventions ne nécessitent pas un rôle administratif.
À utiliser --authmode pour contrôler le type de subvention :
| Value | Behavior | Minimum role |
|---|---|---|
obo (valeur par défaut) |
Subventions déléguées à portée de principal sur l’identité de l’agent SP | Aucun (aucun utilisateur authentifié) |
s2s |
Assignations de rôles d’application sur le SP d’identité d’agent | Administrateur d’Agent ID, Administrateur d’Application ou Administrateur Global |
both |
À la fois des subventions déléguées par l’OBO et des attributions de rôles dans les applications S2S | Rôle S2S (ci-dessus) pour la partie S2S |
# Default — OBO delegated grants (no admin role needed)
a365 setup all
# S2S app role assignments
a365 setup all --authmode s2s
# Both OBO and S2S
a365 setup all --authmode both
Lorsque l’utilisateur connecté ne possède pas le rôle requis pour les subventions S2S, la CLI affiche un bloc de secours PowerShell dans le résumé de configuration. Un administrateur peut l’exécuter pour compléter les devoirs.
Réglez authModea365.config.json pour qu’il s’applique à chaque partie sans le drapeau :
{
"authMode": "s2s"
}
Note
--authmode n’est pas pris en charge avec --aiteammate. Les agents coéquipiers IA utilisent automatiquement l’OBO via l’identité utilisateur de l’agent.
Config sync
Une fois l’exécution réussie, l’interface CLI écrit automatiquement les paramètres d’exécution dans vos fichiers projet :
| Setting | Written to | Description |
|---|---|---|
Connections.ServiceConnection |
appsettings.json / .env |
ID client blueprint, secret client, ID de locataire et point de terminaison de jeton |
Agent365Observability |
appsettings.json / .env |
ID d’agent (identité de l’agent), ID de blueprint, ID de locataire, ID client et secret client pour l’exportation de télémétrie |
TokenValidation |
appsettings.json |
Paramètres de validation de jeton (désactivés par défaut pour non-DW) |
ConnectionsMap |
appsettings.json / .env |
URL de service par défaut pour le mappage de connexion |
L’interface CLI crée le fichier s’il n’existe pas et met à jour des champs individuels sans remplacer le reste de votre configuration.
Réessayer une inscription ayant échoué
Si le programme d’installation termine correctement le blueprint et les autorisations, mais échoue lors de l’inscription de l’agent, utilisez --agent-registration-only cette étape uniquement pour réessayer sans répéter le travail antérieur :
a365 setup all --agent-registration-only