Gérer les environnements et les versions des agents déclaratifs avec Microsoft 365 Agents Toolkit

À mesure que votre agent déclaratif arrive à maturité, vous devez le provisionner dans plusieurs environnements (développement, préproduction et production) et éventuellement exécuter des versions parallèles afin de pouvoir piloter de nouvelles fonctionnalités sans perturber les utilisateurs existants. Le maintien d’un ensemble distinct de fichiers manifestes pour chaque combinaison d’environnement et de version n’est pas évolutif.

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 et en utilisant ${{VAR_NAME}} des espaces réservés dans votre manifeste, le fichier de l’agent déclaratif et m365agents.yml, vous pouvez configurer n’importe quel environnement ou version avec une seule commande,atk provision --env <target> sans dupliquer un seul fichier.

Deux axes, un seul système

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

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

Les deux dimensions sont traitées de la même manière. Vous définissez un fichier d’environnement pour chaque cible et les espaces réservés dans votre manifeste, le fichier d’agent déclaratif et m365agents.yml vous résolvez au moment de la ${{VAR_NAME}} provisionnement.

Modéliser les environnements cibles

La plupart des équipes provisionnent 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 variable 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 environnement différent, passez l’indicateur --env à chaque commande Agents Toolkit :

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

Modéliser plusieurs versions

Les versions d’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 de version 2 (v2) en parallèle d’un agent de version 1 (v1) dans le même client 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 entre les versions :

{
  "$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 distinctes dans le même client. Les utilisateurs qui ont accès à la préversion utilisent la version 2 ; Tous les autres utilisateurs continuent d’utiliser la V1.

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

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

Option A : Conserver un seul declarativeAgent.json et utiliser des variables pour les valeurs qui diffèrent. Cette approche fonctionne bien lorsque les différences sont mineures, par exemple, un autre paragraphe d’instructions ou une autre URL de site SharePoint.

Option B : conserver un fichier d’agent déclaratif distinct par version et le référencer au moyen d’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=v1, la build est résolue en declarativeAgent.v1.json. Lorsque AGENT_VARIANT=v2, il est résolu 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 aucun 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 les uns des ./appPackage/build/ autres et ne se remplacent jamais.

Automatiser les déploiements avec CI/CD

Pour mettre ce modèle à l’échelle dans tous les environnements, utilisez une matrice dans GitHub Actions ou Azure DevOps pour provisionner chaque environnement à partir d’un workflow 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 tâche de matrice charge le fichier correct .env.* et récupère son secret à partir du secret GitHub explicitement mappé. Le mappage explicite est nécessaire, car les noms de secrets GitHub n’autorisent que les lettres majuscules, les chiffres et les tirets bas (par exemple, un nom cible tel que prod-v2 ne peut pas être utilisé directement comme nom secret). Avec cette configuration, l’approvisionnement d’une modification en production après son passage devient un déclencheur de flux de travail plutôt qu’une étape manuelle.

Convention d’affectation de noms

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

Cette convention rend le env/ dossier auto-documenté. Tout membre de l’équipe peut déterminer les environnements existants et ce que chacun cible.

Avantages de cette approche

Passer 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 : provisionnez les versions 1 et 2 dans le même client de production pour les pilotes utilisateurs réels sans dupliquer votre base de code.
• Promotion à commande unique : la réussite --env prod est l’étape de promotion complète. Aucune modification de fichier ou étape de fusion manuelle n’est requise.
• CI/CD cohérent dans tous les environnements : un workflow unique gère chaque environnement avec des étapes identiques, éliminant ainsi 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 remplissant .env.dev.user. Aucune modification de manifeste n’est requise.
• Environnements auditables : chaque environnement dispose d’un seul fichier de source de vérité. Comparaison de ce qui a changé entre prod et prod-v2 est un diff de deux fichiers.

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

Contenu connexe

• Vue d’ensemble de Microsoft 365 Agents Toolkit
• Référence CLI d’Agents Toolkit
• Configurer et déployer avec Agents Toolkit
• Référence au manifeste de l’agent déclaratif
• Présentation des agents déclaratifs
• Publier des agents