Informations de référence sur la commande CLI setup agent 365

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

Syntaxe

a365 setup [command] [options]

Options

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 l’opération terminée, un administrateur général doit effectuer les subventions :

# Non-admin path: run setup, then hand off to Global Administrator
a365 setup all

# Global Administrator completes OAuth2 grants
a365 setup admin --config-dir "<path-to-config-folder>"

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.

Options requirements

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

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

Sous-commandes

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]

Cette commande :

• ToolingManifest.json Lit à partir du deploymentProjectPath fichier spécifié dans a365.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.

Options permissions mcp

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 que McpServers.Mail.All et McpServers.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

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. Ajoutez des autorisations personnalisées à a365.config.json l’aide a365 config permissions avant d’exécuter cette commande.

a365 setup permissions custom [options]

Cette commande :

• 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

Configurer des autorisations personnalisées

Permet a365 config permissions d’ajouter des autorisations personnalisées à votre configuration avant d’exécuter cette commande :

# Add Microsoft Graph extended permissions
a365 config permissions `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Presence.ReadWrite,Files.Read.All,Chat.Read

# Add custom API permissions
a365 config permissions `
  --resource-app-id <your-api-app-id> `
  --scopes CustomScope.Read,CustomScope.Write

# Apply all configured custom permissions
a365 setup permissions custom

Pendant l’installation, le nom de la ressource est résolu automatiquement à partir de Azure. Vous n’avez pas besoin de le spécifier dans la configuration.

Supprimer des autorisations personnalisées

Pour supprimer les autorisations personnalisées de la configuration et de l’Microsoft Entra :

# Step 1: Remove from config
a365 config permissions --reset

# Step 2: Reconcile Microsoft Entra with updated config
a365 setup permissions custom

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 :

1. Schéma
2. 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]

Cette commande :

• 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

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 :

Lorsque vous exécutez a365 setup all sans administrateur général, l’interface CLI :

1. Effectue toutes les étapes qu’il peut effectuer (création de blueprint et autorisations pouvant être héritées).
2. Génère des URL de consentement par administrateur de ressources et les enregistre dans a365.generated.config.json.
3. Affiche les étapes suivantes montrant comment un administrateur général peut effectuer les octrois OAuth2 à l’aide des a365 setup admin URL de consentement générées.

Autorisations minimales requises :

• Rôle développeur d’ID d’agent (pour la création de blueprints)
• Administrateur général (pour les octrois d’autorisations OAuth2 - s’il n’est pas disponible, utilisez setup admin le transfert)

Options setup all

Configuration de l’agent

Par défaut, a365 setup all exécute le flux de l’agent. Ce flux crée un agent sans dépendance Dataverse ou IA. Il fonctionne pour les agents qui communiquent directement avec la plateforme Agent 365 sans nécessiter de licence d’équipe IA.

# Default: uses a365.config.json
a365 setup all

# Or explicitly (same result)
a365 setup all --aiteammate false

Pour exécuter le flux du coéquipier d’IA à la place, passez --aiteammate true.

Ce flux effectue les étapes suivantes dans la séquence :

1. validation Requirements : vérifie les rôles et les prérequis Azure.
2. Création de l’empreinte bleue — crée ou réutilise l’application Blueprint de l’agent Entra ID.
3. 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.
4. Création d’identitéAgent : crée une identité d’agent dans Entra ID via le API Graph d’identité de l’agent.
5. Inscription de l’agent : inscrit l’agent via l’API d’inscription de l’agent AgentX V2.
6. 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).

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-id Passez à remplacer.
• ClientAppId est résolu en recherchant une application Entra nommée Agent 365 CLI dans 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 administrateur général, refusez et utilisez plutôt le flux de travail de setup admin transfert.

Synchronisation de la configuration

Une fois l’exécution réussie, l’interface CLI écrit automatiquement les paramètres d’exécution dans vos fichiers projet :

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-instance-only cette étape uniquement pour réessayer sans répéter le travail antérieur :

a365 setup all --agent-instance-only

setup admin

Termine les octrois d’autorisations OAuth2 (consentement administrateur) qui nécessitent l’administrateur général. Exécutez cette commande après l’exécution a365 setup alld’un administrateur d’ID d’agent ou d’un développeur d’ID d’agent.

Autorisations minimales requises : Administrateur général

a365 setup admin [options]

Quand utiliser setup admin

Utilisez cette commande lorsque :

• Après l’exécution a365 setup alld’un administrateur d’ID d’agent ou d’un développeur d’ID d’agent.
• Le résumé de l’installation montre que les subventions OAuth2 sont en attente et demande à l’administrateur général d’exécuter cette commande.
• Vous souhaitez réexécuter les octrois de consentement après avoir modifié les autorisations dans la configuration.

Flux de travail de transfert classique

# Step 1: Agent ID Admin or Developer runs setup
a365 setup all

# The CLI displays next steps, for example:
# "ACTION REQUIRED — Global Administrator must complete OAuth2 grants"
# "Option 1: a365 setup admin --config-dir '<path-to-config-folder>'"
# "Option 2: Share the consent URL displayed above with your Global Administrator"

# Step 2: Agent ID Admin shares config folder with Global Administrator
# (contains a365.config.json and a365.generated.config.json)

# Step 3: Global Administrator completes the grants
a365 setup admin --config-dir "<path-to-config-folder>"

Cette commande :

• Charge la configuration de l’agent à partir du répertoire spécifié ou du répertoire actif par défaut.
• Lit l’ID de blueprint de l’agent et les autorisations de ressource configurées à partir de la configuration générée.
• Crée des AllPrincipals octrois d’autorisations OAuth2 pour toutes les ressources configurées, notamment :
  • Microsoft Graph (étendues déléguées)
  • Outils Agent 365 (étendues de serveur MCP)
  • API de bot de messagerie
  • API d’observabilité
  • API Power Platform
  • Toutes les autorisations personnalisées définies dans votre configuration
• Affiche une invite de confirmation avant d’apporter des modifications. Permet --yes de contourner l’invite.

Options setup admin

Alternative : URL de consentement

Au lieu d’exécuter a365 setup admin, l’administrateur général peut ouvrir l’URL de consentement combinée qui a365 setup all s’enregistre a365.generated.config.jsonsur . Cette URL couvre toutes les ressources requises dans une seule visite de navigateur.

# Display the generated config to find the consent URL
a365 config display -g
# Look for: combinedAdminConsentUrl