Gerir ambientes e versões para agentes declarativos

À medida que o seu agente declarativo amadurece, tem de implementá-lo em vários ambientes (desenvolvimento, teste e produção) e, eventualmente, executar versões paralelas para poder testar novas capacidades sem perturbar os utilizadores existentes. A manutenção de um conjunto separado de ficheiros de manifesto para cada combinação de ambiente e versão não é dimensionada.

O Toolkit de Agentes do Microsoft 365 aborda os requisitos, o ambiente de destino e a versão do agente, com o mesmo mecanismo: ficheiros de ambiente. Ao definir um .env.* ficheiro por destino de implementação e ao utilizar ${{VAR_NAME}} marcadores de posição em todo o seu manifesto, ficheiro de agente declarativo e m365agents.yml, pode aprovisionar qualquer ambiente ou versão com um único comando,atk provision --env <target> sem duplicar um único ficheiro.

Dois eixos, um sistema

A gestão do ambiente para agentes declarativos tem duas dimensões:

Ambientes de destino: o mesmo agente implementado em inquilinos ou registos de aplicações diferentes : desenvolvimento, teste, produção ou inquilinos específicos do cliente.
Versões do agente: várias variantes do mesmo agente em execução em paralelo, por exemplo, estável v1, pré-visualização v2 ou um ramo experimental.

Ambas as dimensões são processadas da mesma forma. Define um ficheiro de ambiente para cada destino de implementação e os ${{VAR_NAME}} marcadores de posição no seu manifesto, ficheiro de agente declarativo e m365agents.yml resolve no momento do aprovisionamento.

Ambientes de destino de modelos

A maioria das equipas implementa em, pelo menos, dois ambientes (desenvolvimento e produção) e muitas adicionam um ambiente de teste entre os mesmos. Crie um ficheiro por ambiente na env/ pasta:

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

Cada ficheiro define os mesmos nomes de variáveis com valores específicos do 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

Dica

Inclua o nome do ambiente no nome a apresentar do agente para inquilinos de não produção. Por exemplo, "Hr Onboarding Buddy (Staging)" torna imediatamente claro aos técnicos de teste qual a versão que estão a utilizar, o que ajuda a evitar confusões ao comunicar problemas.

Para direcionar um ambiente diferente, transmita o --env sinalizador para cada comando do Toolkit de Agentes:

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

Modelar várias versões

As versões do agente seguem o mesmo padrão que os ambientes de destino. Cada versão é um destino de implementação com o seu próprio ficheiro de ambiente. Para implementar um agente da versão 2 (v2) juntamente com um agente da versão 1 (v1) no mesmo inquilino de produção, adicione um 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

Atribua .env.prod-v2 um ID de aplicação exclusivo do Teams para que ambos os agentes possam coexistir no mesmo 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

Utilize variáveis no seu manifesto para qualquer valor que seja diferente entre versões:

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

O resultado é um ficheiro de manifesto que produz duas aplicações instaláveis distintas no mesmo inquilino. Os utilizadores que receberam a instalação de pré-visualização verão v2; todos os outros utilizadores permanecem na v1.

Observação

O ID da aplicação Teams é a chave para este padrão. A plataforma trata as aplicações com IDs diferentes como instalações separadas, independentemente da quantidade de código que partilham. Esta separação também permite o teste A/B de personas do agente sem qualquer impacto nos utilizadores de produção.

Ramificar a própria definição do agente

Quando as diferenças de versão se estendem para além dos valores variáveis (por exemplo, instruções diferentes, uma nova capacidade ou um conjunto diferente de plug-ins), tem duas opções para ramificar a própria definição do agente.

Opção A: mantenha uma única declarativeAgent.json variável e utilize variáveis para os valores que diferem. Esta abordagem funciona bem quando as diferenças são menores, como um parágrafo de instruções diferente ou um URL de site do SharePoint diferente.

Opção B: Manter um ficheiro de agente declarativo separado por versão e referenciá-lo através de uma variável no manifesto da aplicação Teams:

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

No m365agents.yml, configure o passo do pacote para incluir ${{TEAMSFX_ENV}} no nome do artefacto de saída para que cada ambiente produza um ficheiro 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, a criação é resolvida para declarativeAgent.v1.json. Quando AGENT_VARIANT=v2, resolve para declarativeAgent.v2.json. Ambos os ficheiros são armazenados no repositório e revistos em pedidos Pull, como qualquer outro ficheiro de origem, sem necessidade de sinalizadores de funcionalidade.

Uma vez que o caminho zip de saída inclui ${{TEAMSFX_ENV}}, cada ambiente produz um artefacto com um nome exclusivo. Por exemplo, appPackage.prod.zip e appPackage.prod-v2.zip são escritos de forma independente e nunca substituem uns aos ./appPackage/build/ outros.

Automatizar implementações com CI/CD

Para dimensionar este padrão em todos os ambientes, utilize uma matriz no GitHub Actions ou Azure DevOps para aprovisionar cada ambiente a partir de um único fluxo de trabalho:

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 tarefa de matriz carrega o ficheiro correto .env.* e obtém o segredo do segredo do GitHub explicitamente mapeado. O mapeamento explícito é necessário porque os nomes de segredos do GitHub só permitem letras maiúsculas, dígitos e carateres de sublinhado (por exemplo, um nome de destino como prod-v2 não pode ser utilizado diretamente como um nome secreto). Com esta configuração, promover uma alteração de teste para produção torna-se um acionador de fluxo de trabalho em vez de um passo manual.

Aviso

Não armazene segredos de produção no .env.prod. Utilize .env.prod.user para o desenvolvimento local e o arquivo de segredos CI/CD para execuções de pipelines. Certifique-se de que os .user ficheiros são excluídos e .gitignore nunca consolidados. O pipeline CI/CD deve injetar SECRET_* variáveis no runtime.

Convenção de nomenclatura

Utilize a seguinte convenção de nomenclatura para os seus ficheiros de ambiente.

Padrão	Descrição
`.env.<target>`	Inquilino ou fase: programador, teste, prod
`.env.<target>-<variant>`	Versão ou ramificação dentro de um destino: prod-v2, prod-experimental
`.env.<target>.user`	Segredos desse destino, nunca consolidados
`.env.local`	Configuração do Toolkit de Agentes na raiz do projeto (gerada automaticamente durante o aprovisionamento)

Esta convenção faz com que a env/ pasta se auto-documente. Qualquer membro da equipa pode determinar que ambientes existem e o que cada um visa.

Benefícios desta abordagem

Mover de um manifesto por ambiente para um repositório com muitos ficheiros de ambiente altera o funcionamento da sua equipa:

Versões paralelas sem duplicação de código: implemente v1 e v2 no mesmo inquilino de produção para pilotos de utilizadores reais sem criar o fork da base de código.
Promoção de comando único: Passar --env prod é o passo de promoção completo. Não são necessárias edições de ficheiros ou passos de intercalação manual.
CI/CD consistente entre ambientes: um único fluxo de trabalho processa todos os ambientes com passos idênticos, eliminando o desfasamento de configuração entre o desenvolvimento e a produção.
Integração simplificada: um novo membro da equipa pode começar ao preencher .env.dev.user. Não são necessárias alterações de manifesto.
Implementações auditáveis: cada ambiente tem um único ficheiro de origem de verdade. Comparar o que mudou entre prod e prod-v2 é uma diferença de dois ficheiros.

Esta abordagem trata tanto os ambientes de destino como as versões do agente como destinos de implementação, utilizando as mesmas ferramentas e convenções em toda a parte.

Comentários

Esta página foi útil?

Last updated on 2026-07-02