Administración de entornos y versiones para agentes declarativos

A medida que el agente declarativo madura, debe implementarlo 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. El mantenimiento de un conjunto independiente de archivos de manifiesto para cada entorno y combinación de versiones no se escala.

Microsoft 365 Agents Toolkit aborda los 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 de implementación 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 administración del entorno para agentes declarativos tiene dos dimensiones:

  • Entornos de destino: el mismo agente implementado en diferentes inquilinos o registros de aplicaciones: inquilinos de desarrollo, almacenamiento provisional, producción o 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 controlan de la misma manera. Defina un archivo de entorno para cada destino de implementación y los ${{VAR_NAME}} marcadores de posición del manifiesto, el archivo de agente declarativo y m365agents.yml la resolución en el momento del aprovisionamiento.

Entornos de destino del modelo

La mayoría de los equipos se implementan en al menos 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

Sugerencia

Incluya el nombre del entorno en el nombre para mostrar del agente para los inquilinos que no son de producción. Por ejemplo, "Compañero de incorporación de RR. HH. (ensayo)" deja claro inmediatamente a los evaluadores qué versión usan, lo que ayuda a evitar confusiones al notificar problemas.

Para dirigirse a un entorno diferente, pase la --env marca a cada comando de Agents Toolkit:

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

Modelar varias versiones

Las versiones del 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 de aplicación de Teams único para que ambos agentes puedan coexistir en el mismo inquilino:

# 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 las 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 instalables distintas en el mismo inquilino. Los usuarios que recibieron la instalación en versión preliminar ver v2; todos los demás usuarios permanecen en la versión 1.

Nota:

El identificador de aplicación de Teams es la clave de este patrón. La plataforma trata las aplicaciones con diferentes identificadores como instalaciones independientes, independientemente de la cantidad de código que compartan. Esta separación también permite realizar pruebas A/B de personas de agente sin ningún impacto en los usuarios de producción.

Bifurcar la propia definición del agente

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

Opción A: mantenga una única declarativeAgent.json y 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 de sitio de SharePoint diferente.

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

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

En m365agents.yml, configure el paso del paquete para incluirlo ${{TEAMSFX_ENV}} en el nombre del artefacto de salida para que cada entorno genere 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 en declarativeAgent.v1.json. Cuando AGENT_VARIANT=v2, se resuelve en 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 del archivo ZIP de salida incluye ${{TEAMSFX_ENV}}, cada entorno genera un artefacto con nombre único. Por ejemplo, appPackage.prod.zip y appPackage.prod-v2.zip se escriben de forma independiente en ./appPackage/build/ y nunca se sobrescriben entre sí.

Automatización de 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 de secretos de GitHub solo permiten letras mayúsculas, dígitos y caracteres de subrayado (por ejemplo, un nombre de destino como prod-v2 no se puede usar directamente como nombre de secreto). Con esta configuración, la promoción de un cambio de almacenamiento provisional a producción se convierte en un desencadenador de flujo de trabajo en lugar de en un paso manual.

Advertencia

No almacene secretos de producción en .env.prod. Use .env.prod.user para el desarrollo local y el almacén secreto de CI/CD para las ejecuciones de canalización. Asegúrese de que los .user archivos se excluyen .gitignore y nunca se confirman. La canalización de CI/CD debe insertar SECRET_* variables en tiempo de ejecución.

Convención de nomenclatura

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

Patrón Descripción
.env.<target> Inquilino o fase: desarrollo, ensayo, producción
.env.<target>-<variant> Versión o rama dentro de un destino: prod-v2, prod-experimental
.env.<target>.user Secretos para ese destino, nunca confirmados
.env.local Configuración del kit de herramientas de agentes en la raíz del proyecto (generada automáticamente durante el aprovisionamiento)

Esta convención hace que la env/ carpeta se documente de forma automática. 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 del equipo:

  • Versiones paralelas sin duplicación de código: implemente v1 y v2 en el mismo inquilino de producción para los pilotos de usuario real sin bifurcar el código base.
  • Promoción de comando único: pasar --env prod es el paso de promoción completo. No se requieren modificaciones de archivos ni pasos de combinación manual.
  • CI/CD coherente entre entornos: un único flujo de trabajo controla todos los entornos con pasos idénticos, lo que elimina el desfase 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.
  • Implementaciones auditables: cada entorno tiene un único archivo de origen de verdad. Comparar lo que ha cambiado entre prod y prod-v2 es una diferencia de dos archivos.

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

Contenido relacionado

  • Last updated on