Verwalten von Umgebungen und Versionen für deklarative Agents

Wenn Ihr deklarativer Agent weiterentwickelt wird, 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 stören. Die Verwaltung eines separaten Satzes von Manifestdateien für jede Umgebungs- und Versionskombination wird nicht skaliert.

Das Microsoft 365 Agents Toolkit erfüllt beide Anforderungen( Zielumgebung und Agentversion) mit demselben Mechanismus: Umgebungsdateien. Indem Sie eine .env.* Datei pro Bereitstellungsziel definieren und ${{VAR_NAME}} Platzhalter im gesamten Manifest, in der deklarativen Agent-Datei und m365agents.ymlverwenden, können Sie jede Umgebung oder Version mit einem einzelnen Befehl bereitstellen,atk provision --env <target> ohne eine einzelne Datei zu duplizieren.

Zwei Achsen, ein System

Die Umgebungsverwaltung für deklarative Agents hat zwei Dimensionen:

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

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

Modellzielumgebungen

Die meisten Teams werden in mindestens zwei Umgebungen ( Entwicklung und Produktion) bereitgestellt, 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

Tipp

Fügen Sie den Umgebungsnamen in den Anzeigenamen des Agents für Nicht-Produktionsmandanten ein. Beispielsweise macht "HR Onboarding Buddy (Staging)" Testern sofort klar, welche Version sie verwenden, was hilft, Verwirrung bei der Meldung von Problemen zu vermeiden.

Um eine andere Umgebung als Ziel zu verwenden, übergeben Sie das --env Flag an jeden Agent 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 Umgebung hinzu prod-v2 :

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 gleichzeitig im selben Mandanten vorhanden sein 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

Verwenden Sie Variablen in Ihrem 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 installierbare Apps im selben Mandanten erzeugt. Benutzer, die die Vorschauinstallation erhalten haben, sehen v2; alle anderen Benutzer bleiben auf v1.

Hinweis

Die Teams-App-ID ist der Schlüssel zu diesem Muster. Die Plattform behandelt Apps mit unterschiedlichen IDs als separate Installationen, unabhängig davon, wie viel Code sie gemeinsam nutzen. Diese Trennung ermöglicht auch A/B-Tests von Agent-Personas ohne Auswirkungen auf Produktionsbenutzer.

Verzweigen der Agent-Definition selbst

Wenn Versionsunterschiede über Variablenwerte hinausgehen (z. B. unterschiedliche Anweisungen, eine neue Funktion oder eine andere Gruppe von Plug-Ins), haben Sie zwei Optionen zum Verzweigen der Agent-Definition selbst.

Option A: Behalten Sie einen einzelnen Wert declarativeAgent.json bei, und verwenden Sie Variablen für die werte, die sich unterscheiden. Dieser Ansatz funktioniert gut, wenn die Unterschiede geringfügig sind, z. B. ein anderer Anweisungsabsatz oder eine andere SharePoint-Website-URL.

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

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

m365agents.ymlKonfigurieren Sie in den Paketschritt so, dass er in den Ausgabeartefaktnamen einschließt${{TEAMSFX_ENV}}, damit 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

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

Da der ZIP-Ausgabepfad enthält ${{TEAMSFX_ENV}}, erzeugt jede Umgebung ein eindeutig benanntes Artefakt. Beispielsweise appPackage.prod.zip werden und appPackage.prod-v2.zip unabhängig voneinander ./appPackage/build/ geschrieben und überschreiben sich nie gegenseitig.

Automatisieren von Bereitstellungen mit CI/CD

Um dieses Muster in allen Umgebungen zu skalieren, verwenden Sie eine Matrix in GitHub Actions oder Azure DevOps, um jede Umgebung aus einem 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 GitHub-Geheimnisnamen nur Großbuchstaben, Ziffern und Unterstriche zulassen (z. B. kann ein Zielname wie prod-v2 nicht direkt als Geheimnisname verwendet werden). Mit dieser Konfiguration wird das Höherstufen einer Änderung vom Staging zur Produktion zu einem Workflowtrigger und nicht zu einem manuellen Schritt.

Warnung

Speichern Sie keine Produktionsgeheimnisse in .env.prod. Verwenden Sie .env.prod.user für die lokale Entwicklung und Ihren CI/CD-Geheimnisspeicher für Pipelineausführungen. Stellen Sie sicher, dass die .user Dateien von .gitignore ausgeschlossen und nie committet werden. Ihre CI/CD-Pipeline sollte Variablen zur Laufzeit einfügen SECRET_* .

Namenskonvention

Verwenden Sie die folgende Namenskonvention für Ihre Umgebungsdateien.

Muster	Beschreibung
.env.<target>	Mandant oder Phase: Entwicklung, Staging, Produktion
.env.<target>-<variant>	Version oder Branch innerhalb eines Ziels: prod-v2, prod-experimental
.env.<target>.user	Geheimnisse für dieses Ziel, nie committet
.env.local	Konfiguration des Agents-Toolkits im Projektstamm (automatisch während der Bereitstellung generiert)

Durch diese Konvention wird der env/ Ordner selbstdokumentiert. Jedes Teammitglied kann bestimmen, welche Umgebungen vorhanden sind und auf welche Ziele die einzelnen Umgebungen ausgerichtet sind.

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 im selben Produktionsmandanten für Realbenutzerpiloten bereit, ohne Ihre Codebasis zu forkingen.
• Höherstufung mit nur einem Befehl: Das Übergeben --env prod ist der vollständige Heraufstufungsschritt. Es sind keine Dateibearbeitungen oder manuelle Zusammenführungsschritte erforderlich.
• Konsistente CI/CD über Umgebungen hinweg: Ein einzelner Workflow verarbeitet jede Umgebung mit identischen Schritten, wodurch Konfigurationsabweichungen zwischen Entwicklung und Produktion vermieden werden.
• Vereinfachtes Onboarding: Ein neues Teammitglied kann beginnen, indem es ausgefüllt .env.dev.userwird. Es sind keine Manifeständerungen erforderlich.
• Überprüfbare Bereitstellungen: Jede Umgebung verfügt über eine einzelne Source-of-Truth-Datei. Der Vergleich der Änderungen zwischen prod und prod-v2 ist eine diff von zwei Dateien.

Bei diesem Ansatz werden sowohl Zielumgebungen als auch Agent-Versionen als Bereitstellungsziele behandelt, wobei die gleichen Tools und Konventionen verwendet werden.

Verwandte Inhalte

• Übersicht über das Microsoft 365 Agents Toolkit
• Agents Toolkit CLI-Referenz
• Bereitstellen und Bereitstellen mit dem Agents-Toolkit
• Manifestreferenz für deklarative Agents
• Übersicht über deklarative Agents
• Veröffentlichen von Agents