Gestire ambienti e versioni per gli agenti dichiarativi con Microsoft 365 Agents Toolkit

Man mano che l'agente dichiarativo matura, è necessario eseguirne il provisioning in più ambienti (sviluppo, gestione temporanea e produzione) e infine eseguire versioni parallele in modo da poter testare nuove funzionalità senza interrompere gli utenti esistenti. La gestione di un set separato di file manifesto per ogni combinazione di ambiente e versione non ha alcuna scalabilità.

Microsoft 365 Agents Toolkit risolve sia i requisiti, sia l'ambiente di destinazione che la versione dell'agente, con lo stesso meccanismo: file di ambiente. Definendo un .env.* file per destinazione e utilizzando ${{VAR_NAME}} segnaposto in tutto il manifesto, il file dell'agente dichiarativo e m365agents.yml, è possibile eseguire il provisioning di qualsiasi ambiente o versione con un singolo comando,atk provision --env <target> senza duplicare un singolo file.

Suggerimento

Consigliato: Inizia con Work IQ Dev Tools per scenari di agenti dichiarativi e plug-in pro-code supportati. Vedere la guida introduttiva di WIQD. Le istruzioni basate su toolkit rimangono disponibili per i progetti e i flussi di lavoro esistenti che le richiedono. Controlla il supporto per le funzionalità e l'esperienza di destinazione prima di scegliere uno strumento: WIQD non si rivolge agli agenti del motore personalizzato.

Due assi, un sistema

La gestione dell'ambiente per gli agenti dichiarativi ha due dimensioni:

  • Ambienti di destinazione: lo stesso agente è stato sottoposto a provisioning in tenant o registrazioni di app diversi, ovvero tenant di sviluppo, di gestione temporanea, di produzione o specifici del cliente.
  • Versioni dell'agente: più varianti dello stesso agente in esecuzione in parallelo, ad esempio versione stabile v1, anteprima v2 o ramo sperimentale.

Entrambe le dimensioni vengono gestite allo stesso modo. Puoi definire un file di ambiente per ogni destinazione e i segnaposto nel manifesto, il file dell'agente dichiarativo e m365agents.yml risolvere al momento del ${{VAR_NAME}} provisioning.

Ambienti di destinazione del modello

La maggior parte dei team esegue il provisioning in almeno due ambienti, sviluppo e produzione, e molti aggiungono un ambiente di gestione temporanea tra di essi. Creare un file per ambiente nella env/ cartella:

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

Ogni file definisce gli stessi nomi di variabile con valori specifici dell'ambiente:

# 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

Suggerimento

Includere il nome dell'ambiente nel nome visualizzato dell'agente per i tenant non di produzione. Ad esempio, "HR Onboarding Buddy (Staging)" rende immediatamente chiaro ai tester quale versione stanno usando, evitando così confusione quando si segnalano problemi.

Per scegliere come destinazione un ambiente diverso, passa il --env contrassegno a ciascun comando di Agents Toolkit:

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

Modellare più versioni

Le versioni degli agenti seguono lo stesso modello degli ambienti di destinazione. Ogni versione è una destinazione di distribuzione con il proprio file di ambiente. Per distribuire un agente della versione 2 (v2) insieme a un agente della versione 1 (v1) nello stesso tenant di produzione, aggiungi un prod-v2 ambiente:

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

Specificare .env.prod-v2 un ID app Teams univoco in modo che entrambi gli agenti possano coesistere nello stesso tenant:

# 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

Usa le variabili nel manifesto per qualsiasi valore che differisce tra le versioni:

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

Il risultato è un file manifesto che produce due app distinte nello stesso tenant. Gli utenti a cui è stato concesso l'accesso all'anteprima usano la versione 2; Tutti gli altri utenti continuano a usare la versione 1.

Nota

L'ID dell'app Teams è la chiave di questo modello. La piattaforma considera le app con ID diversi come app separate, indipendentemente dalla quantità di codice che condividono. Questa separazione consente anche di eseguire test A/B degli utenti tipo agente senza alcun impatto sugli utenti di produzione.

Creare un ramo della definizione dell'agente stesso

Quando le differenze di versione si estendono oltre i valori delle variabili (ad esempio, istruzioni diverse, una nuova funzionalità o un diverso set di plug-in), sono disponibili due opzioni per la ramificazione della definizione dell'agente stesso.

Opzione A: mantenere un singolo declarativeAgent.json e usare variabili per i valori diversi. Questo approccio è particolarmente adatto quando le differenze sono minime, ad esempio un paragrafo di istruzioni diverso o un URL di un sito di SharePoint diverso.

Opzione B: Mantenere un file agente dichiarativo separato per ogni versione e farvi riferimento tramite una variabile nel manifesto dell'app Teams:

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

In m365agents.yml, configurare il passaggio del pacchetto da includere ${{TEAMSFX_ENV}} nel nome dell'artefatto di output in modo che ogni ambiente produca un file ZIP distinto:

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

Quando AGENT_VARIANT=v1, la build viene risolta in declarativeAgent.v1.json. Quando AGENT_VARIANT=v2, si risolve in declarativeAgent.v2.json. Entrambi i file vengono archiviati nel repository ed esaminati nelle richieste pull come qualsiasi altro file di origine, senza flag di funzionalità necessari.

Poiché il percorso zip di output include ${{TEAMSFX_ENV}}, ogni ambiente produce un artefatto denominato in modo univoco. Ad esempio, appPackage.prod.zip e appPackage.prod-v2.zip sono scritti indipendentemente e non si sovrascrivono mai l'uno sull'altro ./appPackage/build/ .

Automatizzare le distribuzioni con CI/CD

Per ridimensionare questo modello in tutti gli ambienti, usare una matrice in GitHub Actions o Azure DevOps per eseguire il provisioning di ogni ambiente da un singolo flusso di lavoro:

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

Ogni processo della matrice carica il file corretto .env.* e ne recupera il segreto dal segreto GitHub mappato esplicitamente. Il mapping esplicito è necessario perché i nomi segreti di GitHub consentono solo lettere maiuscole, cifre e caratteri di sottolineatura (ad esempio, un nome di destinazione come prod-v2 non può essere usato direttamente come nome segreto). Con questa configurazione, il provisioning di una modifica alla produzione dopo aver superato la gestione temporanea diventa un trigger del flusso di lavoro anziché un passaggio manuale.

Avviso

Non memorizzare segreti di produzione in .env.prod. Usare .env.prod.user per lo sviluppo locale e l'archivio segreto CI/CD per le esecuzioni della pipeline. Verificare che i .user file siano esclusi e .gitignore non siano mai stati sottoposti a commit. La pipeline CI/CD deve inserire SECRET_* le variabili in fase di esecuzione.

Convenzione di denominazione

Usa la seguente convenzione di denominazione per i file di ambiente.

Schema Descrizione
.env.<target> Tenant o fase: sviluppo, gestione temporanea, produzione
.env.<target>-<variant> Versione o ramo all'interno di una destinazione: prod-v2, prod-experimental
.env.<target>.user Segreti per quel bersaglio, mai impegnati
.env.local Configurazione di Agents Toolkit nella radice del progetto (generata automaticamente durante il provisioning)

Questa convenzione rende la env/ cartella autodocumentata. Qualsiasi membro del team può determinare quali ambienti esistono e a cosa destinati ciascuno.

Vantaggi di questo approccio

Il passaggio da un manifesto per ambiente a un repository con molti file di ambiente cambia il modo in cui opera il team:

  • Versioni parallele senza duplicazione del codice: effettua il provisioning di v1 e v2 nello stesso tenant di produzione per i programmi pilota di utenti reali senza creare fork della codebase.
  • Promozione a comando singolo: il passaggio --env prod è la fase di promozione completa. Non sono necessarie modifiche ai file o passaggi di unione manuali.
  • CI/CD coerenti tra gli ambienti: un unico flusso di lavoro gestisce ogni ambiente con passaggi identici, eliminando la deriva della configurazione tra sviluppo e produzione.
  • Onboarding semplificato: un nuovo membro del team può iniziare compilando .env.dev.user. Non sono necessarie modifiche al manifesto.
  • Ambienti controllabili: ogni ambiente ha un singolo file di origine della verità. Confrontando ciò che è cambiato tra prod e prod-v2 è un diff di due file.

Questo approccio considera sia gli ambienti di destinazione che le versioni dell'agente come destinazioni di distribuzione, utilizzando gli stessi strumenti e le stesse convenzioni.