Verwalten von Umgebungen und Versionen für deklarative Agents mit dem Microsoft 365 Agents Toolkit

Wenn Ihr deklarativer Agent ausgereift ist, müssen Sie ihn in mehreren Umgebungen bereitstellen – Entwicklung, Staging und Produktion – und schließlich parallele Versionen ausführen, damit Sie neue Funktionen testen können, ohne vorhandene Benutzer zu unterbrechen. Die Verwaltung eines separaten Satzes von Manifestdateien für jede Umgebungs- und Versionskombination ist nicht skalierbar.

Das Microsoft 365 Agents Toolkit erfüllt beide Anforderungen, die Zielumgebung und die Agent-Version, mit demselben Mechanismus: Umgebungsdateien. Indem Sie eine .env.* Datei pro Ziel definieren und ${{VAR_NAME}} Platzhalter in Ihrem gesamten Manifest, Ihrer deklarativen Agentdatei und m365agents.ymlverwenden, können Sie jede Umgebung oder Version mit einem einzigen Befehlatk provision --env <target> bereitstellen, ohne eine einzelne Datei zu duplizieren.

Zwei Achsen, ein System

Das Umgebungsmanagement für deklarative Agenten hat zwei Dimensionen:

• Zielumgebungen: Derselbe Agent wird für verschiedene Mandanten oder App-Registrierungen bereitgestellt – Entwicklungs-, Staging-, Produktions- oder kundenspezifische Mandanten.
• Agent-Versionen: Mehrere Varianten desselben Agents, die parallel ausgeführt werden, z. B. v1 stable, v2 preview oder ein experimenteller Zweig.

Beide Dimensionen werden auf die gleiche Weise behandelt. Sie definieren eine Umgebungsdatei für jedes Ziel und die ${{VAR_NAME}} Platzhalter in Ihrem Manifest, der deklarativen Agent-Datei und m365agents.yml lösen sie zum Bereitstellungszeitpunkt auf.

Zielumgebungen modellieren

Die meisten Teams stellen mindestens zwei Umgebungen bereit – Entwicklung und Produktion – und viele fügen eine Stagingumgebung dazwischen hinzu. Erstellen Sie eine Datei pro Umgebung im env/ Ordner:

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

Jede Datei definiert dieselben Variablennamen mit umgebungsspezifischen Werten:

# 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

Um eine andere Umgebung als Ziel zu verwenden, übergeben Sie das --env Flag an jeden Agents Toolkit-Befehl:

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

Modellieren mehrerer Versionen

Agent-Versionen folgen demselben Muster wie Zielumgebungen. Jede Version ist ein Bereitstellungsziel mit einer eigenen Umgebungsdatei. Um einen Agent der Version 2 (v2) zusammen mit einem Agent der Version 1 (v1) im selben Produktionsmandanten bereitzustellen, fügen Sie eine prod-v2 Umgebung hinzu:

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

Geben Sie .env.prod-v2 eine eindeutige Teams-App-ID an, damit beide Agents im selben Mandanten koexistieren können:

# 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

Verwende Variablen in deinem Manifest für jeden Wert, der sich zwischen den Versionen unterscheidet:

{
  "$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"
      }
    ]
  }
}

Das Ergebnis ist eine Manifestdatei, die zwei verschiedene Apps im selben Mandanten erzeugt. Benutzer, denen Zugriff auf die Vorschauversion gewährt wird, verwenden v2; Alle anderen Benutzer verwenden weiterhin v1.

Verzweigung der Agentdefinition selbst

Wenn Versionsunterschiede über Variablenwerte hinausgehen (z. B. unterschiedliche Anweisungen, eine neue Funktion oder ein anderer Satz von Plug-Ins), haben Sie zwei Möglichkeiten, die Agentendefinition selbst zu verzweigen.

Option A: Behalten Sie eine einzelne declarativeAgent.json Spalte bei und verwenden Sie Variablen für die Werte, die sich unterscheiden. Dieser Ansatz funktioniert gut, wenn die Unterschiede geringfügig sind, z. B. bei einem anderen Anweisungsabsatz oder einer anderen SharePoint Website-URL.

Option B: Verwalten Sie eine separate deklarative Agent-Datei pro Version und verweisen Sie über eine Variable im Teams-App-Manifest darauf:

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

Konfigurieren m365agents.ymlSie den Paketschritt so, dass er im Namen des Ausgabeartefakts enthalten ist ${{TEAMSFX_ENV}} , sodass jede Umgebung eine eigene ZIP-Datei erzeugt:

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

Wenn AGENT_VARIANT=v1, wird der Build in declarativeAgent.v1.jsonaufgelöst. Wenn AGENT_VARIANT=v2, wird es aufgelöst in declarativeAgent.v2.json. Beide Dateien werden im Repository gespeichert und wie jede andere Quelldatei in Pull Requests überprüft, ohne dass Featureflags erforderlich sind.

Da der Ausgabe-ZIP-Pfad ${{TEAMSFX_ENV}}enthält, erzeugt jede Umgebung ein Artefakt mit eindeutig benanntem Namen. Beispielsweise werden appPackage.prod.zip unabhängig voneinander geschrieben ./appPackage/build/ und appPackage.prod-v2.zip überschreiben sich niemals.

Automatisieren von Bereitstellungen mit CI/CD

Um dieses Muster über alle Umgebungen hinweg zu skalieren, verwenden Sie eine Matrix in GitHub Actions oder Azure DevOps, um jede Umgebung über einen einzelnen Workflow bereitzustellen:

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 }}

Jeder Matrixauftrag lädt die richtige .env.* Datei und ruft sein Geheimnis aus dem explizit zugeordneten GitHub-Geheimnis ab. Die explizite Zuordnung ist erforderlich, da geheime GitHub-Namen nur Großbuchstaben, Ziffern und Unterstriche zulassen (z. B. kann ein Zielname nicht prod-v2 direkt als Geheimnisname verwendet werden). Mit dieser Konfiguration wird die Bereitstellung einer Änderung in der Produktion nach dem Staging zu einem Workflow-Trigger und nicht zu einem manuellen Schritt.

Namenskonvention

Verwenden Sie die folgende Namenskonvention für Ihre Umgebungsdateien.

Durch diese Konvention wird der env/ Ordner selbstdokumentierend. Jedes Teammitglied kann bestimmen, welche Umgebungen vorhanden sind und worauf sie jeweils abzielen.

Vorteile dieses Ansatzes

Der Wechsel von einem Manifest pro Umgebung zu einem Repository mit vielen Umgebungsdateien ändert die Arbeitsweise Ihres Teams:

• Parallele Versionen ohne Codeduplizierung: Stellen Sie v1 und v2 für denselben Produktionsmandanten für Pilotprojekte mit realen Benutzern bereit, ohne Ihre Codebasis zu forken.
• Höherstufung mit einem Befehl: Das Bestehen --env prod ist der vollständige Beförderungsschritt. Es sind keine Dateibearbeitungen oder manuellen Schritte zum Zusammenführen erforderlich.
• Konsistentes CI/CD in allen Umgebungen: Ein einziger Workflow bewältigt jede Umgebung mit identischen Schritten, wodurch Konfigurationsabweichungen zwischen Entwicklung und Produktion vermieden werden.
• Vereinfachtes Onboarding: Ein neues Teammitglied kann beginnen, indem .env.dev.useres . Es sind keine Manifeständerungen erforderlich.
• Überwachbare Umgebungen: Jede Umgebung verfügt über eine einzige Source-of-Truth-Datei. Compare, was sich zwischen prod und prod-v2 geändert hat, ist ein Diff zweier Dateien.

Dieser Ansatz behandelt sowohl Zielumgebungen als auch Agentversionen als Bereitstellungsziele, wobei durchgehend dieselben Tools und Konventionen verwendet werden.

Verwandte Inhalte

• Übersicht über das Microsoft 365 Agents-Toolkit
• CLI-Referenz zum Agents-Toolkit
• Bereitstellen und Bereitstellen mit Agents Toolkit
• Deklarative Agentmanifestreferenz
• Übersicht über deklarative Agents
• Veröffentlichen von Agents