宣言型エージェントの環境とバージョンを管理する

宣言型エージェントが成熟したら、それを複数の環境 (開発、ステージング、運用) にデプロイし、最終的に並列バージョンを実行して、既存のユーザーを中断することなく新しい機能をパイロットできるようにする必要があります。 環境とバージョンの組み合わせごとに個別のマニフェスト ファイルのセットを維持しても、スケーリングは行われません。

Microsoft 365 Agents Toolkit は、環境ファイルと同じメカニズムを使用して、ターゲット環境とエージェントバージョンの両方の要件に対応します。 デプロイ ターゲットごとに 1 つの.env.* ファイルを定義し、マニフェスト、宣言型エージェント ファイル、m365agents.yml全体で ${{VAR_NAME}} プレースホルダーを使用することで、単一のファイルを複製することなく、任意の環境またはバージョンを 1 つのコマンド (atk provision --env <target>) でプロビジョニングできます。

2 軸、1 つのシステム

宣言型エージェントの環境管理には、次の 2 つのディメンションがあります。

• ターゲット環境: 異なるテナントまたはアプリの登録 (開発、ステージング、運用、または顧客固有のテナント) にデプロイされたのと同じエージェント。
• エージェント バージョン: 並列で実行されている同じエージェントの複数のバリアント (v1 安定版、v2 プレビュー、試験的ブランチなど)。

どちらのディメンションも同じ方法で処理されます。 デプロイ ターゲットごとに環境ファイルを定義し、マニフェスト、宣言型エージェント ファイル、m365agents.ymlプロビジョニング時に解決する${{VAR_NAME}} プレースホルダーを定義します。

ターゲット環境をモデル化する

ほとんどのチームは、少なくとも 2 つの環境 (開発と運用) にデプロイし、多くのチームがそれらの間にステージング環境を追加します。 env/ フォルダーに環境ごとに 1 つのファイルを作成します。

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

別の環境をターゲットにするには、各 Agents Toolkit コマンドに --env フラグを渡します。

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

結果は、同じテナントに 2 つの個別のインストール可能なアプリを生成する 1 つのマニフェスト ファイルです。 プレビュー インストールを受け取ったユーザーには、v2 が表示されます。他のすべてのユーザーは v1 に残ります。

エージェント定義自体を分岐する

バージョンの違いが変数値を超える場合 (たとえば、異なる命令、新しい機能、別のプラグインのセットなど)、エージェント定義自体を分岐するための 2 つのオプションがあります。

オプション A: 1 つの 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に解決されます。 どちらのファイルもリポジトリに格納され、他のソース ファイルと同様に pull request で確認され、機能フラグは必要ありません。

出力 zip パスには ${{TEAMSFX_ENV}}が含まれているため、各環境は一意の名前の成果物を生成します。 たとえば、 appPackage.prod.zip と appPackage.prod-v2.zip は、 ./appPackage/build/ に個別に書き込まれ、互いに上書きされることはありません。

CI/CD を使用してデプロイを自動化する

すべての環境でこのパターンをスケーリングするには、GitHub Actionsまたは Azure DevOps のマトリックスを使用して、1 つのワークフローから各環境をプロビジョニングします。

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/ フォルダーが自己文書化されます。 どのチーム メンバーでも、存在する環境と、それぞれのターゲットを決定できます。

このアプローチの利点

環境ごとに 1 つのマニフェストから多数の環境ファイルを含む 1 つのリポジトリに移動すると、チームの動作が変更されます。

• コードの重複のない並列バージョン: コードベースをフォークすることなく、実際のユーザー パイロット用に v1 と v2 を同じ運用テナントにデプロイします。
• 単一コマンドの昇格: --env prod の渡しは、完全な昇格手順です。 ファイルの編集や手動のマージ手順は必要ありません。
• 環境間で一貫した CI/CD: 1 つのワークフローが同じ手順ですべての環境を処理し、開発と運用環境の間の構成ドリフトを排除します。
• 簡単なオンボード: 新しいチーム メンバーは、 .env.dev.userに入力することで開始できます。 マニフェストの変更は必要ありません。
• 監査可能なデプロイ: 各環境には、単一の信頼できるソース ファイルがあります。 prodとprod-v2の間で何が変更されたかを比較することは、2 つのファイルのdiffです。

このアプローチでは、ターゲット環境とエージェント バージョンの両方をデプロイ ターゲットとして扱います。この方法では、全体を通して同じツールと規則を使用します。

関連コンテンツ

• Microsoft 365 エージェント ツールキットの概要
• Agents Toolkit CLI リファレンス
• エージェント ツールキットを使用したプロビジョニングとデプロイ
• 宣言型エージェント マニフェストのリファレンス
• 宣言型エージェントの概要
• エージェントを発行する