Configuration de l’Agent 365

La CLI d’Agent 365 a besoin de connaître des informations telles que votre tenant, votre abonnement, et d’autres détails pour créer les ressources nécessaires, comme le modèle d'agent Agent Blueprint. La CLI stocke ces informations dans un fichier de configuration central appelé a365.config.json dans votre répertoire de travail. Toutes les commandes de la CLI utilisent ce fichier de configuration.

Prerequisites

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

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

Autorisations requises :

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

Configurez la ligne de commande Agent 365

La a365 config init commande crée a365.config.json, le fichier de configuration central utilisé par toutes les commandes CLI de l’Agent 365, dans votre répertoire de travail. L'interface CLI fournit un assistant interactif avec intégration de l'Azure CLI et des valeurs par défaut optimisées pour réduire les entrées manuelles.

S’authentifier avec Azure

Avant d’initialiser la configuration, authentifiez-vous avec Azure à l’aide de la commande az login :

az login

Sélectionnez l’abonnement approprié lorsque vous y êtes invité(e). L'assistant de configuration utilise Azure CLI pour interroger les abonnements, les groupes de ressources et les plans App Service disponibles. Pour une expérience de développement fluide, configurez votre compte utilisateur locataire avec le bon rôle et les bonnes permissions, abonnement et plan de service d’application avant de commencer.

Initialiser la configuration

Exécutez la a365 config init commande pour lancer l’assistant de configuration interactif :

a365 config init

L’Assistant utilise l’intégration avec Azure CLI et des valeurs par défaut intelligentes pour minimiser les entrées manuelles. Vous êtes invité à :

L’assistant génère automatiquement les noms de ressources associés (application web, identité de l’agent, blueprint, utilisateur agent) et valide le type de projet de votre équipe. Avant d’enregistrer, vous pouvez éventuellement configurer des autorisations de blueprint personnalisées pour les ressources externes (telles que la présence Teams ou les fichiers OneDrive) et personnaliser n'importe lequel des noms générés.

En savoir plus sur la structure des fichiers de configuration

Vérifier les fichiers de configuration d'Agent 365

L’Agent 365 utilise plusieurs fichiers de configuration tout au long du cycle de développement :

Après avoir terminé la configuration, vérifiez que vous avez les éléments suivants :

Vérifier la création du a365.config.json fichier

Vérifiez visuellement que le a365.config.json fichier existe. Ou bien, utilisez la commande PowerShell Test-Path dans un script pour automatiser cette vérification.

# Check file exists in current working directory
Test-Path a365.config.json
# Should return: True

Vérifier a365.config.json les données de configuration

Exécutez la a365 config display commande pour visualiser la configuration actuelle de la CLI de l’Agent 365.

a365 config display

Le résultat de cette commande ressemble à ceci :

{
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "resourceGroup": "your-resource-group",
  "location": "location-of-your-azure-resources",
  "environment": "prod",
  "needDeployment": true,
  "clientAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "appServicePlanName": "your-app-service-plan",
  "appServicePlanSku": "service-plan-sku",
  "webAppName": "your-web-app",
  "agentIdentityDisplayName": "your-agent-name Identity",
  "agentBlueprintDisplayName": "your-agent-name Blueprint",
  "agentUserPrincipalName": "youragent@yourtenant.onmicrosoft.com",
  "agentUserDisplayName": "your-agent-name Agent User",
  "managerEmail": "manager@yourtenant.com",
  "agentUserUsageLocation": "usage-location",
  "deploymentProjectPath": "C:\\path\\to\\your\\project",
  "agentDescription": "your-agent-name - Agent 365 Agent"
}

Liste de contrôle de la vérification

✅ Tous les champs ont des valeurs valides (pas de chaînes vides ni de nulls)
✅ tenantId et subscriptionId sont des GUID valides
✅ clientAppId est un GUID valide (votre enregistrement personnalisé de l'application cliente)
✅ resourceGroup et appServicePlanName existent dans votre abonnement Azure
✅ managerEmail utilise votre domaine de l'instance
✅ deploymentProjectPath pointe vers votre répertoire de codes d’agent
✅ agentUserPrincipalName suit le format agentname@tenant.com
✅ environment est défini (typiquement prod)
✅ needDeployment est true pour la configuration initiale. Si vous n’avez pas besoin de déploiement, apprenez à définir un point de terminaison de messagerie agent.

Si votre configuration ne correspond pas à la sortie attendue, consultez la section Dépannage pour des solutions détaillées.

Ajoutez a365.generated.config.json à votre fichier .gitignore. Ce fichier contient des secrets générés et ne doit jamais être validé dans la gestion du code source.

Étape suivante

Si tout est en ordre, vous êtes prêt à continuer.

Résolution des problèmes

Suivez ces étapes pour diagnostiquer rapidement et résoudre les problèmes courants avec a365.config.json et l'Agent 365 CLI.

• Le fichier de configuration n’existe pas
• Valeurs de configuration manquantes ou non valides
• Client ou abonnement non valide
• Échec de la validation d’application cliente personnalisée
• Nom d’utilisateur de l’agent non valide
• Nom de l’application web déjà pris

Le fichier de configuration n’existe pas

Symptôme: Les commandes CLI échouent avec « Configuration non trouvée » ou Test-Path a365.config.json retournent False.

Solution : Créez un nouveau a365.config.json fichier.

Effectuez les étapes de Authenticate avec Azure et Initialize configuration.

Valeurs de configuration manquantes ou non valides

Symptôme: Le fichier de configuration existe mais comporte des champs vides ou des erreurs de validation.

Solution : Suivez les étapes pour vérifier a365.config.json les données de configuration.

Si un champ est incorrect :

• Option 1 : Relancez le magicien en utilisant la a365 config init commande.
• Option 2 : Éditez a365.config.json manuellement avec les bonnes valeurs.

Locataire ou abonnement non valide

Symptôme: La CLI échoue avec des erreurs d’authentification ou d’autorisation.

Solution:

Utilisez ces commandes pour réauthentifier avec Azure, vérifier le compte connecté, basculer vers l’abonnement approprié et réinitialiser la configuration de l’interface CLI Agent 365.

# Re-authenticate with Azure
az login

# Verify you're logged into the correct account
az account show

# If needed, switch to the correct subscription
az account set --subscription "<subscription-name-or-id>"

# Re-initialize configuration
a365 config init

Échec de la validation d’application cliente personnalisée

Symptôme: L’assistant de configuration échoue lors de la validation de l’ID client personnalisé.

Solution : Examinez l’enregistrement personnalisé de votre application client pour vous assurer que votre inscription dispose de toutes les autorisations requises et de l’autorisation de l’administrateur.

Nom principal d'utilisateur de l'agent non valide

Symptôme: La validation échoue pour le nom d’utilisateur principal de l’agent pendant la configuration.

Solution: Vérifiez que l’UPN suit le format username@domain. Par exemple : demo.agent@contoso.onmicrosoft.com. Un suffixe de domaine manquant est la cause la plus courante.

Nom de l’application web déjà pris

Symptôme: Le programme d’installation échoue, car le nom de l’application web est déjà utilisé.

Solution : Les noms d’applications web doivent être globalement uniques dans Azure. Mettez à jour webAppName avec une valeur unique dans a365.config.json, ou réexécutez a365 config init pour générer un nouveau nom.