使用 Microsoft 365 Agents Toolkit 管理宣告式代理程式的環境和版本

隨著宣告式代理程式的成熟,您必須將其佈建至多個環境 (開發、暫存和生產) ,並最終執行平行版本,以便在不中斷現有使用者的情況下試驗新功能。 為每個環境和版本組合維護一組單獨的資訊清單檔案無法縮放。

Microsoft 365 代理程式工具組使用相同的機制:環境檔案來滿足目標環境和代理程式版本這兩個需求。 透過為每個目標定義一個 .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 應用程式識別碼,讓兩個代理程式可以共存於相同的租用戶中:

# 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 的應用程序視為單獨的應用程序,無論它們共享多少代碼。 這種分離還可以對代理程式角色進行 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。 用於 .env.prod.user 本機開發,並用於管線執行的 CI/CD 密碼存放區。 確保 .user 檔案已 .gitignore 排除且永不認可。 您的 CI/CD 管線應該在執行階段插入 SECRET_* 變數。

命名慣例

請針對環境檔案使用下列命名慣例。

模式 描述
.env.<target> 租用戶或階段:開發、中繼、生產
.env.<target>-<variant> 目標內的版本或分支: prod-v2, prod-experimental
.env.<target>.user 該目標的密碼,永不認可
.env.local 專案根目錄中的 Agents Toolkit 設定 (在佈建期間自動產生)

此慣例可讓 env/ 資料夾自我記錄。 任何團隊成員都可以決定存在哪些環境以及每個環境的目標。

這個方法的優點

從每個環境一個資訊清單移至一個包含許多環境檔案的存放庫,會變更團隊的運作方式:

  • 沒有程式碼重複的平行版本:為真實使用者試驗佈建 v1 和 v2 至相同的生產租用戶,而不需要分支您的程式碼庫。
  • 單指令晉級:通過 --env prod 是完整的晉級步驟。 不需要編輯檔案或手動合併步驟。
  • 跨環境一致的 CI/CD:單一工作流程以相同的步驟處理每個環境,消除開發和生產之間的設定漂移。
  • 簡化入職:新的團隊成員可以透過填寫 .env.dev.user來開始。 不需要進行資訊清單變更。
  • 可稽核的環境:每個環境都有單一事實來源檔案。 比較兩個檔案之間的 prod 變更內容 和 prod-v2 是兩個檔案的差異。

此方法會將目標環境和代理程式版本視為部署目標,並始終使用相同的工具和慣例。