Administrar entornos y versiones de agentes declarativos con el Kit de herramientas de agentes de Microsoft 365

A medida que el agente declarativo madura, debe aprovisionarlo en varios entornos (desarrollo, ensayo y producción) y, finalmente, ejecutar versiones paralelas para que pueda probar nuevas funcionalidades sin interrumpir a los usuarios existentes. Mantener un conjunto independiente de archivos de manifiesto para cada combinación de entorno y versión no escala.

El Kit de herramientas de agentes de Microsoft 365 aborda ambos requisitos, el entorno de destino y la versión del agente, con el mismo mecanismo: archivos de entorno. Al definir un .env.* archivo por destino y usar ${{VAR_NAME}} marcadores de posición en todo el manifiesto, el archivo de agente declarativo y m365agents.yml, puede aprovisionar cualquier entorno o versión con un solo comando,atk provision --env <target> sin duplicar un solo archivo.

Dos ejes, un sistema

La gestión del entorno para agentes declarativos tiene dos dimensiones:

• Entornos de destino: el mismo agente aprovisionado a diferentes inquilinos o registros de aplicaciones (desarrollo, ensayo, producción o inquilinos específicos del cliente).
• Versiones del agente: varias variantes del mismo agente que se ejecutan en paralelo, por ejemplo, v1 estable, versión preliminar v2 o una rama experimental.

Ambas dimensiones se manejan de la misma manera. Defina un archivo de entorno para cada destino y los marcadores de posición en el manifiesto, el archivo de agente declarativo y m365agents.yml resuelva en el momento de ${{VAR_NAME}} la aprovisionamiento.

Entornos de destino del modelo

La mayoría de los equipos se proporcionan al menos a dos entornos (desarrollo y producción) y muchos agregan un entorno de ensayo entre ellos. Cree un archivo por entorno en la env/ carpeta:

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

Cada archivo define los mismos nombres de variable con valores específicos del entorno:

# 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

Para dirigirse a un entorno diferente, pase la marca a cada comando del kit de herramientas de --env agentes:

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

Modelar varias versiones

Las versiones de agente siguen el mismo patrón que los entornos de destino. Cada versión es un destino de implementación con su propio archivo de entorno. Para implementar un agente de versión 2 (v2) junto con un agente de versión 1 (v1) en el mismo inquilino de producción, agregue un prod-v2 entorno:

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

Proporcione .env.prod-v2 un identificador único de la aplicación de Teams para que ambos agentes puedan coexistir en el mismo espacio empresarial:

# 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

Use variables en el manifiesto para cualquier valor que difiera entre versiones:

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

El resultado es un archivo de manifiesto que genera dos aplicaciones distintas en el mismo inquilino. Los usuarios a los que se les da acceso a la versión preliminar usan v2; El resto de usuarios seguirán usando la versión 1.

Bifurcar la propia definición del agente

Cuando las diferencias de versión se extienden más allá de los valores variables (por ejemplo, instrucciones diferentes, una nueva capacidad o un conjunto diferente de complementos), tiene dos opciones para ramificar la definición del agente en sí.

Opción A: Mantenga uno y declarativeAgent.json use variables para los valores que difieren. Este enfoque funciona bien cuando las diferencias son menores, como un párrafo de instrucciones diferente o una dirección URL del sitio de SharePoint diferente.

Opción B: Mantenga un archivo de agente declarativo independiente por versión y haga referencia a él mediante una variable en el manifiesto de la aplicación de Teams:

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

En m365agents.yml, configura el paso del paquete para incluir ${{TEAMSFX_ENV}} en el artefacto de salida el nombre de modo que cada entorno produzca un archivo zip distinto:

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

Cuando AGENT_VARIANT=v1, la compilación se resuelve como declarativeAgent.v1.json. Cuando AGENT_VARIANT=v2, se resuelve como declarativeAgent.v2.json. Ambos archivos se almacenan en el repositorio y se revisan en solicitudes de incorporación de cambios como cualquier otro archivo de origen, sin necesidad de marcas de características.

Dado que la ruta de acceso postal de salida incluye ${{TEAMSFX_ENV}}, cada entorno produce un artefacto con un nombre único. Por ejemplo, appPackage.prod.zip y se escriben de forma independiente ./appPackage/build/ y appPackage.prod-v2.zip nunca se sobrescriben entre sí.

Automatizar implementaciones con CI/CD

Para escalar este patrón en todos los entornos, use una matriz en Acciones de GitHub o Azure DevOps para aprovisionar cada entorno desde un único flujo de trabajo:

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

Cada trabajo de matriz carga el archivo correcto .env.* y recupera su secreto del secreto de GitHub asignado explícitamente. La asignación explícita es necesaria porque los nombres secretos de GitHub solo permiten letras mayúsculas, dígitos y guiones bajos (por ejemplo, un nombre de destino como prod-v2 no se puede usar directamente como un nombre secreto). Con esta configuración, el aprovisionamiento de un cambio en producción después de que pase por el ensayo se convierte en un desencadenador de flujo de trabajo en lugar de un paso manual.

Convenciones de nomenclatura

Use la siguiente convención de nomenclatura para los archivos de entorno.

Esta convención hace que la env/ carpeta se documente por sí misma. Cualquier miembro del equipo puede determinar qué entornos existen y a qué se dirige cada uno.

Ventajas de este enfoque

Pasar de un manifiesto por entorno a un repositorio con muchos archivos de entorno cambia el funcionamiento de su equipo:

• Versiones paralelas sin duplicación de código: aprovisione v1 y v2 en el mismo inquilino de producción para pilotos de usuario real sin bifurcar el código base.
• Promoción de un solo comando: Pasar --env prod es el paso completo de la promoción. No es necesario editar archivos ni seguir pasos de combinación manual.
• CI/CD coherente en todos los entornos: un único flujo de trabajo gestiona todos los entornos con pasos idénticos, lo que elimina la desviación de configuración entre el desarrollo y la producción.
• Incorporación simplificada: un nuevo miembro del equipo puede empezar rellenando .env.dev.user. No se requieren cambios en el manifiesto.
• Entornos auditables: cada entorno tiene un único archivo de fuente de verdad. Comparando lo que cambió entre prod y prod-v2 es una diferencia de dos archivos.

Este enfoque trata tanto los entornos de destino como las versiones del agente como destinos de implementación, utilizando las mismas herramientas y convenciones en todo momento.

Contenido relacionado

• Información general del kit de herramientas de agentes de Microsoft 365
• Referencia de la CLI del kit de herramientas de agentes
• Aprovisionar e implementar con Agents Toolkit
• Referencia de manifiesto de agente declarativo
• Información general sobre agentes declarativos
• Publicar agentes