Gerenciar ambientes e versões para agentes declarativos

À medida que seu agente declarativo amadurece, você precisa implantá-lo em vários ambientes — desenvolvimento, preparo e produção — e, eventualmente, executar versões paralelas para que possa testar novos recursos sem interromper os usuários existentes. Manter um conjunto separado de arquivos de manifesto para cada combinação de ambiente e versão não é escalonável.

O Microsoft 365 Agents Toolkit atende aos dois requisitos, ambiente de destino e versão do agente, com o mesmo mecanismo: arquivos de ambiente. Definindo um .env.* arquivo por destino de implantação e usando ${{VAR_NAME}} espaços reservados em todo o manifesto, arquivo de agente declarativo e m365agents.yml, você pode provisionar qualquer ambiente ou versão com um único comando,atk provision --env <target> sem duplicar um único arquivo.

Dois eixos, um sistema

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

• Ambientes de destino: o mesmo agente implantado em diferentes locatários ou registros de aplicativo — desenvolvimento, preparo, produção ou locatários específicos do cliente.
• Versões do agente: várias variantes do mesmo agente em execução em paralelo — por exemplo, v1 estável, versão prévia v2 ou uma ramificação experimental.

Ambas as dimensões são tratadas da mesma maneira. Você define um arquivo de ambiente para cada destino de implantação e os espaços reservados em seu manifesto${{VAR_NAME}}, arquivo de agente declarativo e m365agents.yml resolve no momento do provisionamento.

Modelar ambientes de destino

A maioria das equipes é implantada em pelo menos dois ambientes — desenvolvimento e produção — e muitas adicionam um ambiente de preparo entre eles. Crie um arquivo por ambiente na env/ pasta:

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

Cada arquivo 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

Para direcionar um ambiente diferente, passe o --env sinalizador para cada comando do Agents Toolkit:

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 dos ambientes de destino. Cada versão é um destino de implantação com seu próprio arquivo de ambiente. Para implantar um agente da versão 2 (v2) junto com um agente da versão 1 (v1) no mesmo locatário 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

Forneça .env.prod-v2 uma ID do aplicativo Teams exclusiva para que ambos os agentes possam coexistir no mesmo locatário:

# 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 variáveis em seu manifesto para qualquer valor que seja diferente entre as 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 arquivo de manifesto que produz dois aplicativos instaláveis distintos no mesmo locatário. Usuários que receberam a instalação de visualização consulte v2; Todos os outros usuários permanecem na v1.

Ramificar a própria definição de agente

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

Opção A: Mantenha um único declarativeAgent.json e use variáveis para os valores que diferem. Essa abordagem funciona bem quando as diferenças são pequenas, como um parágrafo de instruções diferente ou uma URL diferente do site do SharePoint.

Opção B: manter um arquivo de agente declarativo separado por versão e referenciá-lo por meio de uma variável no manifesto do aplicativo Teams:

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

Em m365agents.yml, configure a etapa do pacote a ser incluída ${{TEAMSFX_ENV}} no nome do artefato de saída para que cada ambiente produza um arquivo 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 compilação é resolvida para declarativeAgent.v1.json. Quando AGENT_VARIANT=v2, ele resolve declarativeAgent.v2.jsoncomo . Ambos os arquivos são armazenados no repositório e revisados em solicitações de pull como qualquer outro arquivo de origem, sem a necessidade de sinalizadores de recurso.

Como o caminho zip de saída inclui ${{TEAMSFX_ENV}}, cada ambiente produz um artefato com nome exclusivo. Por exemplo, appPackage.prod.zip e appPackage.prod-v2.zip são gravados independentemente e nunca substituem um ao ./appPackage/build/ outro.

Automatizar implantações com CI/CD

Para dimensionar esse padrão em todos os ambientes, use uma matriz no GitHub Actions ou no Azure DevOps para provisionar 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 trabalho de matriz carrega o arquivo correto .env.* e recupera seu segredo do segredo do GitHub mapeado explicitamente. O mapeamento explícito é necessário porque os nomes secretos do GitHub permitem apenas letras maiúsculas, dígitos e sublinhados (por exemplo, um nome de destino como prod-v2 não pode ser usado diretamente como um nome secreto). Com essa configuração, promover uma alteração do preparo para a produção torna-se um gatilho de fluxo de trabalho em vez de uma etapa manual.

Convenção de nomenclatura

Use a seguinte convenção de nomenclatura para seus arquivos de ambiente.

Essa convenção faz com que a env/ pasta se autodocumente. Qualquer membro da equipe pode determinar quais ambientes existem e o que cada um tem como alvo.

Benefícios desta abordagem

Passar de um manifesto por ambiente para um repositório com muitos arquivos de ambiente muda a forma como sua equipe opera:

• Versões paralelas sem duplicação de código: implante v1 e v2 no mesmo locatário de produção para pilotos de usuário real sem bifurcar sua base de código.
• Promoção de comando único: A aprovação --env prod é a etapa completa da promoção. Não são necessárias edições de arquivo ou etapas de mesclagem manual.
• CI/CD consistente em todos os ambientes: um único fluxo de trabalho lida com todos os ambientes com etapas idênticas, eliminando o desvio de configuração entre o desenvolvimento e a produção.
• Integração simplificada: um novo membro da equipe pode começar preenchendo .env.dev.usero . Nenhuma alteração de manifesto é necessária.
• Implantações auditáveis: cada ambiente tem um único arquivo de fonte de verdade. Comparando o que mudou entre prod and prod-v2 é uma diferença de dois arquivos.

Essa abordagem trata os ambientes de destino e as versões do agente como destinos de implantação, usando as mesmas ferramentas e convenções por toda parte.

Conteúdo relacionado

• Visão geral do Kit de Ferramentas de Agentes do Microsoft 365
• Referência da CLI do Kit de Ferramentas de Agentes
• Provisionar e implantar com o Agents Toolkit
• Referência do manifesto do agente declarativo
• Visão geral dos agentes declarativos
• Publicar agentes