Gérer les environnements et les versions des agents déclaratifs

À mesure que votre agent déclaratif évolue, vous devez le déployer dans plusieurs environnements (développement, préproduction et production), puis exécuter des versions parallèles afin de pouvoir tester de nouvelles fonctionnalités sans perturber les utilisateurs existants. La gestion d’un ensemble distinct de fichiers manifestes pour chaque combinaison d’environnement et de version n’est pas mise à l’échelle.

Microsoft 365 Agents Toolkit répond à la fois aux exigences, à l’environnement cible et à la version de l’agent, avec le même mécanisme : les fichiers d’environnement. En définissant un .env.* fichier par cible de déploiement et en utilisant ${{VAR_NAME}} des espaces réservés dans votre manifeste, fichier d’agent déclaratif et m365agents.yml, vous pouvez provisionner n’importe quel environnement ou version avec une seule commande,atk provision --env <target> sans dupliquer un seul fichier.

Deux axes, un système

La gestion de l’environnement pour les agents déclaratifs a deux dimensions :

• Environnements cibles : le même agent déployé sur différents locataires ou inscriptions d’applications (développement, préproduction, production ou locataires spécifiques au client).
• Versions de l’agent : plusieurs variantes du même agent s’exécutant en parallèle, par exemple, v1 stable, préversion v2 ou branche expérimentale.

Les deux dimensions sont gérées de la même façon. Vous définissez un fichier d’environnement pour chaque cible de déploiement et les ${{VAR_NAME}} espaces réservés dans votre manifeste, fichier d’agent déclaratif et m365agents.yml résolvez au moment de l’approvisionnement.

Environnements cibles de modèle

La plupart des équipes déploient dans au moins deux environnements (développement et production), et beaucoup ajoutent un environnement intermédiaire entre eux. Créez un fichier par environnement dans le env/ dossier :

env/
├── .env.dev
├── .env.dev.user
├── .env.staging
├── .env.staging.user
├── .env.prod
└── .env.prod.user

Chaque fichier définit les mêmes noms de variables avec des valeurs spécifiques à l’environnement :

# env/.env.staging
TEAMS_APP_ID=33333333-3333-3333-3333-333333333333
AAD_CLIENT_ID=44444444-4444-4444-4444-444444444444
API_BASE_URL=https://api-staging.contoso.com
SHAREPOINT_SITE_URL=https://contoso.sharepoint.com/sites/hr-staging
AGENT_DISPLAY_NAME=HR Onboarding Buddy (Staging)
TEAMSFX_ENV=staging

Pour cibler un autre environnement, passez l’indicateur --env à chaque commande Agent Toolkit :

atk provision --env staging
atk deploy --env staging
atk publish --env staging

Modéliser plusieurs versions

Les versions de l’agent suivent le même modèle que les environnements cibles. Chaque version est une cible de déploiement avec son propre fichier d’environnement. Pour déployer un agent version 2 (v2) avec un agent version 1 (v1) dans le même locataire de production, ajoutez un prod-v2 environnement :

env/
├── .env.dev
├── .env.staging
├── .env.prod          # v1, the stable one
├── .env.prod-v2       # v2, running side by side
└── ...corresponding .user files

Donnez .env.prod-v2 un ID d’application Teams unique afin que les deux agents puissent coexister dans le même locataire :

# env/.env.prod-v2
TEAMS_APP_ID=55555555-5555-5555-5555-555555555555
AAD_CLIENT_ID=22222222-2222-2222-2222-222222222222
API_BASE_URL=https://api.contoso.com
SHAREPOINT_SITE_URL=https://contoso.sharepoint.com/sites/hr
AGENT_DISPLAY_NAME=HR Onboarding Buddy (Preview)
AGENT_VERSION=2.0.0
TEAMSFX_ENV=prod-v2

Utilisez des variables dans votre manifeste pour toute valeur qui diffère d’une version à l’autre :

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.24/MicrosoftTeams.schema.json",
  "manifestVersion": "1.24",
  "id": "${{TEAMS_APP_ID}}",
  "version": "${{AGENT_VERSION}}",
  "name": {
    "short": "${{AGENT_DISPLAY_NAME}}",
    "full": "${{AGENT_DISPLAY_NAME}} - Contoso"
  },
  "developer": {
    "name": "Contoso",
    "websiteUrl": "${{API_BASE_URL}}"
  },
  "copilotAgents": {
    "declarativeAgents": [
      {
        "id": "declarativeAgent",
        "file": "declarativeAgent.json"
      }
    ]
  }
}

Le résultat est un fichier manifeste qui produit deux applications installables distinctes dans le même locataire. Les utilisateurs qui ont reçu l’installation en préversion voient v2 ; tous les autres utilisateurs restent sur v1.

Brancher la définition de l’agent elle-même

Lorsque les différences de version s’étendent au-delà des valeurs de variable (par exemple, différentes instructions, une nouvelle fonctionnalité ou un ensemble différent de plug-ins), vous avez deux options pour brancher la définition de l’agent elle-même.

Option A : Conservez une seule declarativeAgent.json et utilisez des variables pour les valeurs qui diffèrent. Cette approche fonctionne bien lorsque les différences sont mineures, comme un paragraphe d’instructions différent ou une URL de site SharePoint différente.

Option B : Conservez un fichier d’agent déclaratif distinct par version et référencez-le via une variable dans le manifeste de l’application Teams :

{
  "copilotAgents": {
    "declarativeAgents": [
      {
        "id": "declarativeAgent",
        "file": "declarativeAgent.${{AGENT_VARIANT}}.json"
      }
    ]
  }
}

Dans m365agents.yml, configurez l’étape du package à inclure ${{TEAMSFX_ENV}} dans le nom de l’artefact de sortie afin que chaque environnement produise un fichier zip distinct :

provision:
  - uses: teamsApp/zipAppPackage
    with:
      manifestPath: ./appPackage/manifest.json
      outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
      outputFolder: ./appPackage/build

Lorsque AGENT_VARIANT=v1la valeur est , la build est résolue en declarativeAgent.v1.json. Quand AGENT_VARIANT=v2la valeur est , elle est résolue en declarativeAgent.v2.json. Les deux fichiers sont stockés dans le référentiel et examinés dans des demandes de tirage comme n’importe quel autre fichier source, sans indicateur de fonctionnalité requis.

Étant donné que le chemin zip de sortie inclut ${{TEAMSFX_ENV}}, chaque environnement produit un artefact nommé de manière unique. Par exemple, appPackage.prod.zip et appPackage.prod-v2.zip sont écrits indépendamment dans ./appPackage/build/ et ne se remplacent jamais.

Automatiser les déploiements avec CI/CD

Pour mettre à l’échelle ce modèle dans tous les environnements, utilisez une matrice dans GitHub Actions ou Azure DevOps pour provisionner chaque environnement à partir d’un flux de travail unique :

strategy:
  matrix:
    include:
      - target: dev
        secret_name: AAD_SECRET_DEV
      - target: staging
        secret_name: AAD_SECRET_STAGING
      - target: prod
        secret_name: AAD_SECRET_PROD
      - target: prod-v2
        secret_name: AAD_SECRET_PROD_V2
steps:
  - uses: actions/checkout@v4
  - run: npm install -g @microsoft/m365agentstoolkit-cli
  - run: atk provision --env ${{ matrix.target }}
    env:
      SECRET_AAD_CLIENT_SECRET: ${{ secrets[matrix.secret_name] }}
  - run: atk deploy --env ${{ matrix.target }}

Chaque travail de matrice charge le fichier correct .env.* et récupère son secret à partir du secret GitHub mappé explicitement. Le mappage explicite est requis, car les noms de secrets GitHub autorisent uniquement les lettres majuscules, les chiffres et les traits de soulignement (par exemple, un nom cible comme prod-v2 ne peut pas être utilisé directement comme nom secret). Avec cette configuration, la promotion d’un passage de la préproduction à la production devient un déclencheur de workflow plutôt qu’une étape manuelle.

Convention de nommage

Utilisez la convention d’affectation de noms suivante pour vos fichiers d’environnement.

Cette convention rend le env/ dossier auto-documenté. N’importe quel membre de l’équipe peut déterminer quels environnements existent et ce que chacun cible.

Avantages de cette approche

Le passage d’un manifeste par environnement à un référentiel avec de nombreux fichiers d’environnement modifie le fonctionnement de votre équipe :

• Versions parallèles sans duplication de code : déployez v1 et v2 sur le même locataire de production pour les pilotes utilisateur réels sans duplication de codebase.
• Promotion à commande unique : la réussite --env prod est l’étape de promotion complète. Aucune modification de fichier ou aucune étape de fusion manuelle n’est requise.
• Ci/CD cohérent entre les environnements : un flux de travail unique gère chaque environnement avec des étapes identiques, ce qui élimine la dérive de configuration entre le développement et la production.
• Intégration simplifiée : un nouveau membre de l’équipe peut commencer en .env.dev.userremplissant . Aucune modification du manifeste n’est requise.
• Déploiements auditables : chaque environnement a un fichier de source de vérité unique. La comparaison de ce qui a changé entre prod et prod-v2 est une diff de deux fichiers.

Cette approche traite les environnements cibles et les versions de l’agent comme des cibles de déploiement, en utilisant les mêmes outils et conventions.

Contenu connexe

• Vue d’ensemble du kit de ressources Microsoft 365 Agents
• Informations de référence sur l’interface CLI d’Agents Toolkit
• Provisionner et déployer avec agents Toolkit
• Informations de référence sur le manifeste de l’agent déclaratif
• Vue d’ensemble des agents déclaratifs
• Publier des agents