Microsoft 365 Agents Toolkit を使用して宣言型エージェントの環境とバージョンを管理する

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

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

2 軸、1 システム

宣言型エージェントの環境管理には、以下の 2 つの側面があります。

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

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

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

ほとんどのチームは、少なくとも 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 のマトリックスを使用して、単一のワークフローから各環境をプロビジョニングします。

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: 単一のワークフローですべての環境を同じ手順で処理し、開発と本番の間の構成のドリフトを排除します。
• オンボーディングの簡素化: 新しいチーム メンバーは、.env.dev.userに入力することで作業を開始できます。 マニフェストを変更する必要はありません。
• 監査可能な環境: 各環境には、信頼できる唯一のソース ファイルがあります。 prod と prod-v2 の間で何が変更されたかを比較すると、2 つのファイルのdiffになります。

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

関連コンテンツ

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