宣言型エージェントが成熟したら、それを複数の環境 (開発、ステージング、運用) にデプロイし、最終的に並列バージョンを実行して、既存のユーザーを中断することなく新しい機能をパイロットできるようにする必要があります。 環境とバージョンの組み合わせごとに個別のマニフェスト ファイルのセットを維持しても、スケーリングは行われません。
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
ヒント
運用環境以外のテナントのエージェントの表示名に環境名を含めます。 たとえば、"HR Onboarding Buddy (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 に残ります。
注:
Teams アプリ ID がこのパターンの鍵です。 プラットフォームは、共有するコードの量に関係なく、異なる ID を持つアプリを個別のインストールとして扱います。 この分離により、運用ユーザーに影響を与えることなく、エージェント ペルソナの A/B テストも可能になります。
エージェント定義自体を分岐する
バージョンの違いが変数値を超える場合 (たとえば、異なる命令、新しい機能、別のプラグインのセットなど)、エージェント定義自体を分岐するための 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.prodに格納しないでください。 ローカル開発には .env.prod.user 、パイプライン実行には CI/CD シークレット ストアを使用します。
.user ファイルが.gitignoreによって除外され、コミットされていないことを確認します。 CI/CD パイプラインは、実行時に SECRET_* 変数を挿入する必要があります。
名前付け規則
環境ファイルには、次の名前付け規則を使用します。
| パターン | 説明 |
|---|---|
.env.<target> |
テナントまたはステージ: 開発、ステージング、prod |
.env.<target>-<variant> |
ターゲット内のバージョンまたはブランチ: prod-v2、prod-experimental |
.env.<target>.user |
そのターゲットのシークレット(コミットなし) |
.env.local |
プロジェクト ルートでのエージェント ツールキットの構成 (プロビジョニング中に自動生成) |
この規則により、 env/ フォルダーが自己文書化されます。 どのチーム メンバーでも、存在する環境と、それぞれのターゲットを決定できます。
このアプローチの利点
環境ごとに 1 つのマニフェストから多数の環境ファイルを含む 1 つのリポジトリに移動すると、チームの動作が変更されます。
- コードの重複のない並列バージョン: コードベースをフォークすることなく、実際のユーザー パイロット用に v1 と v2 を同じ運用テナントにデプロイします。
-
単一コマンドの昇格:
--env prodの渡しは、完全な昇格手順です。 ファイルの編集や手動のマージ手順は必要ありません。 - 環境間で一貫した CI/CD: 1 つのワークフローが同じ手順ですべての環境を処理し、開発と運用環境の間の構成ドリフトを排除します。
-
簡単なオンボード: 新しいチーム メンバーは、
.env.dev.userに入力することで開始できます。 マニフェストの変更は必要ありません。 -
監査可能なデプロイ: 各環境には、単一の信頼できるソース ファイルがあります。
prodとprod-v2の間で何が変更されたかを比較することは、2 つのファイルのdiffです。
このアプローチでは、ターゲット環境とエージェント バージョンの両方をデプロイ ターゲットとして扱います。この方法では、全体を通して同じツールと規則を使用します。