使用 Microsoft 365 Agents Toolkit 管理声明式代理的环境和版本

随着声明式代理的成熟,你需要将其预配到多个环境(开发、暂存和生产),并最终运行并行版本,以便在不中断现有用户的情况下试用新功能。 为每个环境和版本组合维护一组单独的清单文件无法伸缩。

Microsoft 365 Agents Toolkit 使用相同的机制满足目标环境和代理版本这两个要求:环境文件。 通过为每个目标定义一个 .env.* 文件,并在 ${{VAR_NAME}} 整个清单、声明性代理文件和 m365agents.yml中使用占位符,只需一个命令atk provision --env <target>即可预配任何环境或版本,而无需复制单个文件。

提示

受到推崇的: 从 Work IQ 开发工具 开始,用于受支持的专业代码声明代理和插件方案。 请参阅 WIQD 快速入门。 基于工具包的说明仍然可用于需要它们的现有项目和工作流。 在选择工具之前,请检查 功能和目标体验支持 : WIQD 不面向自定义引擎代理。

两个轴,一个系统

声明式代理的环境管理有两个维度:

  • 目标环境:同一代理预配到不同的租户或应用程序注册(开发、暂存、生产或客户特定租户)。
  • 代理版本:并行运行的同一代理的多个变体 — 例如 v1 稳定版、v2 预览版或实验性分支。

这两个维度的处理方式相同。 您可以为每个目标定义一个环境文件, ${{VAR_NAME}} 以及清单、声明性代理文件中的占位符,并在 m365agents.yml 预配时解析。

对目标环境进行建模

大多数团队至少预配到两个环境(开发和生产),许多团队在它们之间添加临时环境。 在文件夹中 env/ 为每个环境创建一个文件:

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

每个文件都定义具有特定于环境的值的相同变量名称:

# 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

提示

在非生产租户的代理显示名称中包含环境名称。 例如,“HR Onboarding Buddy (Staging) ”可让测试人员立即清楚地知道他们正在使用哪个版本,这有助于避免在报告问题时出现混淆。

要面向不同的环境,请将 --env 标志传递给每个 Agents Toolkit 命令:

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

对多个版本进行建模

代理版本遵循与目标环境相同的模式。 每个版本都是具有其自己的环境文件的部署目标。 若要在同一生产租户中将版本 2 (v2) 代理与版本 1 (v1) 代理一起部署,请添加一个 prod-v2 环境:

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

提供 .env.prod-v2 唯一的 Teams 应用 ID,以便两个代理可以在同一租户中共存:

# 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

在清单中对版本之间的任何值使用变量:

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

结果是一个清单文件在同一租户中生成两个不同的应用。 有权访问预览版的用户使用 v2;所有其他用户将继续使用 v1。

注意

Teams 应用 ID 是此模式的关键参数。 平台将具有不同 ID 的应用视为单独的应用,无论它们共享多少代码。 这种分离还支持代理角色的 A/B 测试,而不会对生产用户产生任何影响。

分支代理定义本身

当版本差异超出变量值 (例如,不同的指令、新功能或一组不同的插件) 时,有两个选项用于分支代理定义本身。

选项 A:保留单变量 declarativeAgent.json ,并对不同的值使用变量。 此方法适用于差异很小的情况,例如不同的说明段落或不同的 SharePoint 网站 URL。

选项 B:每个版本维护单独的声明性代理文件,并通过 Teams 应用清单中的变量引用它:

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

在 m365agents.yml中,配置要包含在 ${{TEAMSFX_ENV}} 输出工件名称中的包步骤,以便每个环境生成不同的 zip 文件:

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

当 AGENT_VARIANT=v1,生成解析为 declarativeAgent.v1.json. 当 AGENT_VARIANT=v2时,它解析为 declarativeAgent.v2.json。 这两个文件都存储在存储库中,并像任何其他源文件一样在拉取请求中进行审查,不需要任何功能标志。

由于输出 zip 路径包含 ${{TEAMSFX_ENV}},因此每个环境都会生成唯一命名的工件。 例如, appPackage.prod.zip 和 appPackage.prod-v2.zip 独立写入 ./appPackage/build/ ,并且永远不会相互覆盖。

使用 CI/CD 自动部署

若要跨所有环境缩放此模式,请使用 GitHub Actions 或 Azure DevOps 中的矩阵从单个工作流预配每个环境:

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

每个矩阵作业都会加载正确的 .env.* 文件,并从显式映射的 GitHub 机密中检索其机密。 显式映射是必需的,因为 GitHub 机密名称只允许大写字母、数字和下划线, (例如,目标名称(如)不能 prod-v2 直接用作机密名称) 。 使用此配置,在更改通过暂存后预配到生产将成为工作流触发器,而不是手动步骤。

警告

请勿在 .env.prod中存储生产机密。 用于本地开发,CI .env.prod.user /CD 机密存储用于管道运行。 确保 .user 文件已 .gitignore 排除在外并且从不提交。 CI/CD 管道应在运行时注入 SECRET_* 变量。

命名约定

对环境文件使用以下命名约定。

模式 说明
.env.<target> 租户或暂存:开发、暂存、生产
.env.<target>-<variant> 目标内的版本或分支:prod-v2、prod-experimental
.env.<target>.user 该目标的机密,从未提交
.env.local 项目根目录中的代理工具包配置 (在预配期间自动生成)

此约定使 env/ 文件夹自记录。 任何团队成员都可以确定存在哪些环境以及每个环境的目标。

此方法的优点

从每个环境一个清单移动到包含多个环境文件的一个存储库会改变团队的运作方式:

  • 无代码重复的并行版本:为真实用户试点预配 v1 和 v2 到同一生产租户,而无需对代码库进行分叉。
  • 单指令晋升:通过 --env prod 是完整的晋升步骤。 无需文件编辑或手动合并步骤。
  • 跨环境一致的 CI/CD:单个工作流程以相同的步骤处理每个环境,消除了开发和生产之间的配置偏差。
  • 简化的载入: 新的团队成员可以通过填写 .env.dev.user. 不需要清单更改。
  • 可审计的环境:每个环境都有一个单一的事实来源文件。 比较两个文件之间prodprod-v2更改的内容 和 是两个文件的差异。

此方法将目标环境和代理版本视为部署目标,始终使用相同的工具和约定。