| name | copilot-studio-v2 |
| description | Copilot Studio の「全く新しいアーキテクチャ」（cliagent テンプレート）エージェントを Dataverse Web API だけで完全自動構築する。UI 手動作成不要。Bot 作成・Instructions/モデル/メモリ設定・フラット Python スキル添付・アイコン登録・公開までスクリプトで完結。MCP サーバー（Dataverse / Work IQ 等）のツール追加は Copilot Studio UI での手動作業とする。 |
| category | automation |
| triggers | ["Copilot Studio v2","新しいアーキテクチャ","全く新しいアーキテクチャ","cliagent","CLICopilotRecognizer","エージェント自動構築","API でエージェント作成","コードファースト エージェント","フラットスキル","Python スキル","InlineAgentSkill","スキルバンドル","BotConfiguration","agentSettings","enableMemory","Sonnet46","エージェント v2","エージェント アイコン","Dataverse MCP","Work IQ","PvaPublish","エージェント 公開"] |
Copilot Studio v2（新アーキテクチャ）エージェント構築スキル
Copilot Studio の 「全く新しいアーキテクチャ」（cliagent テンプレート） エージェントを
Dataverse Web API だけで完全自動構築 する。
v1（旧）スキルとの最大の違い
| 観点 | v1（copilot-studio スキル / 旧アーキ） | v2（本スキル / 新アーキ cliagent） |
|---|
| Bot 作成 | ❌ API 不可。Copilot Studio UI で手動作成必須 | ✅ POST /bots で API 作成可能。UI 不要・完全自動 |
| 設定の保存先 | GPT コンポーネント（componenttype=15）+ PVA ダブル改行 YAML | bots.configuration の BotConfiguration JSON にインライン |
| recognizer | （クラシック PVA） | CLICopilotRecognizer |
| モデル指定 | GPT data の aISettings.model.modelNameHint | agentSettings.model.series（例 Sonnet46） |
| Instructions | GPT data YAML（ダブル改行フォーマット注意） | agentSettings.instructions.segments[].value（プレーン文字列） |
| メモリ | （個別設定） | agentSettings.enableMemory: true |
| スキル | （ナレッジ/トピック） | フラット Python スキルバンドル（type=9 + type=14 子ファイル） |
| 自動化適性 | △ UI 介在が必要 | ◎ エンドツーエンドでスクリプト完結 |
このスキルを選ぶ理由: Bot 作成からスキル添付まで 人手の UI 操作ゼロ で構築できる。
CI/再現構築・量産・プログラム的な改変に向く。
いつ v2 を使うか（architecture スキルでの分岐）
architecture スキルの Copilot Studio 選定時に、ユーザーへ v2 / v1 のどちらで作るか を確認する。
判断の起点は「他サービスと連携して使うか、単独で使うか」:
- 連携利用（Code Apps / Web サイト / 他システムから呼び出す）→ v1 を推奨。
v2（cliagent）は Code Apps から呼び出せず・Web サイトにも埋め込めない致命的制約があるため。
- 単独利用（Teams / Copilot Studio 単体の対話のみ）→ v2 を推奨（UI 操作なしで自動構築できるため）。
致命的制約: v2 のエージェントは Code Apps の ExecuteCopilotAsyncV2 連携や WebChat SDK での
外部公開に対応しない。これらのシナリオでは必ず v1 を選ぶ。
| v2（新アーキ）が向く＝単独利用 | v1（旧アーキ）が向く＝連携利用 |
|---|
| Teams 等で単独利用し、外部から呼び出さない | Code Apps / Web サイト / 他システムから呼び出す（v2 不可） |
| UI 操作なしで自動構築したい | 外部公開（Web 埋め込み・WebChat SDK）・トリガー・ニュース配信の既存資産を流用したい |
| フラット Python スキルでツール挙動を実装したい | conversationStarters / 会話の開始 / クイック返信を細かく作り込みたい |
| 再現構築・量産・プログラム的改変 | クラシックなナレッジ/トピック中心の構成 |
構築フロー（完全自動）
1. .env 準備（DATAVERSE_URL / TENANT_ID / 任意で SOLUTION_NAME・PUBLISHER_PREFIX）
2. 設計提示 → ユーザー承認（名前・Instructions・モデル・スキル・アイコン・MCP 構成）
- ファイル出力を伴うスキルを添付する場合は、Instructions に
「ファイルを出力する際は毎回異なるファイル名にする」旨を含める（同名だと UI でダウンロード不可）
3. scripts/create_agent.py … cliagent Bot を API 作成 + プロビジョニング待ち
4. scripts/set_icon.py … アイコン登録（240 / Teams color 192 / outline 32）
5. scripts/set_app_details.py … Edit details(説明文・開発元・リンク・Teams 設定・M365 有効化)
6. scripts/attach_skill.py … フラット Python スキルを添付（type=9 + type=14）
7. scripts/publish_agent.py … PvaPublish で公開
8. scripts/verify_agent.py … 構造検証（filedata 実体ダウンロード確認）
9. pac copilot list … Published / Active / Provisioned を確認
10. UI で MCP サーバーを追加（Dataverse / Work IQ 等）… ★手動作業（後述）
11. Preview で動作テスト（ユーザー）
一括実行: 上記 3〜7 は scripts/deploy_agent.py で
ワンショット実行できる（.env の構成に従い作成→アイコン→Edit details→スキル→公開を連結）。
MCP サーバーの追加は自動化対象外のため、この一括実行には含まれない。
MCP サーバーの追加は Copilot Studio UI での手動作業（重要）
MCP サーバー（Dataverse MCP / Work IQ 等）のツール追加は、Copilot Studio UI から手動で行う
前提とする。以前は Dataverse Web API（botcomponent type=9 の McpTool）で自動追加する手順を
提供していたが、接続参照の命名規約・公開後の「確認(Confirm)」操作など UI 側の状態に依存する
挙動が多く、API 経由での自動化は事故りやすい。そのため本スキルでは MCP ツール追加を
スクリプト化しない。詳細な手動手順は MCP サーバーの追加 を参照。
必須要件・落とし穴（実機検証済み）
Bot 作成は cliagent テンプレートなら API で成功する
✅ POST /bots に template="cliagent-1.0.0" を指定すれば API 作成できる
→ pac copilot list で Provisioned / Active になる
⚠️ bots.synchronizationstatus は一時的に "Provisioning" のまま残ることがある
→ pac copilot list の表示が正となる（Provisioned なら利用可）
configuration は BotConfiguration JSON
{
"$kind": "BotConfiguration",
"channels": [{ "$kind": "ChannelDefinition", "id": "MsTeams", "channelId": "MsTeams" }],
"recognizer": { "$kind": "CLICopilotRecognizer" },
"agentSettings": {
"$kind": "AgentSettings",
"model": { "$kind": "ModelConfig", "series": "Sonnet46" },
"instructions": {
"$kind": "Instructions",
"segments": [{ "$kind": "StaticSegment", "value": "<エージェントの指示文>" }]
},
"enableMemory": true
}
}
- Instructions はプレーン文字列。v1 のような PVA ダブル改行 YAML は不要。
- 既存 Bot を改変する場合は
configuration を GET → ディープマージ → PATCH（モデル・メモリを失わない）。
- ファイルを出力するスキルを持つ場合は、Instructions に「ファイル出力時は毎回異なるファイル名にする
（日時や UUID を付与する）」旨を必ず含める。Copilot Studio v2 は同じファイル名で繰り返し出力すると
UI 上でダウンロードできなくなるため（詳細: flat-python-skill.md）。
スキルは「フラット Python バンドル」
新ランタイムの制約（実機で確認）:
❌ JavaScript / pptxgenjs は拒否される → ✅ Python（python-pptx 等）のみ
❌ バンドル内のサブフォルダ階層は解決されない → ✅ フラット（同一階層に全ファイル）
❌ 同梱画像ファイルが読み込まれないことがある → ✅ 画像は assets_b64.py に Base64 埋め込み
詳細は フラット Python スキルの書き方 を参照。
スキルバンドルの botcomponent 構造
| componenttype | 役割 | 格納先 | 親バインド |
|---|
| 9 | InlineAgentSkill（スキル本体） | data 列 | parentbotid@odata.bind → /bots(...) |
| 14 | FileAttachmentComponent（同梱ファイル） | filedata File 列 | ParentBotComponentId@odata.bind → /botcomponents(...) |
- type=9 の
data: kind: InlineAgentSkill\r\ncontent: <!-- bic:bundle={bundle_id} -->
- type=14 子の 親ナビゲーションプロパティは
ParentBotComponentId（Pascalケース。parentbotcomponentid は不可）
filedata は PATCH /botcomponents({id})/filedata に生バイト + ヘッダ x-ms-file-name でアップロード
詳細は スキルバンドル構造 を参照。
アイコン・公開（実機検証済み）
✅ アイコンは bots.iconbase64(240) ＋ teams.colorIcon(192)/outlineIcon(32) の 3 か所へ登録
⚠ bots を PATCH する際は name 列を必ず同送（無いと 0x80040265 エラー）
✅ 公開は PvaPublish。状態確認は pac copilot list（publishedon は None のことがある）
MCP サーバーの追加は API 自動化の対象外（UI での手動作業）。手順は
MCP サーバーの追加 を参照。
詳細は アイコン登録と公開 を参照。
よくあるエラー
異常系（症状→原因→対処の一覧）は references/troubleshooting.md を参照。
スクリプト一覧
認証: 全スクリプトは standard スキルの auth_helper.py を使用する（requests 直呼び禁止）。
サブリファレンス
.env 必須項目
.env.example は references/.env.example を参照。
DATAVERSE_URL=https://<org>.crm.dynamics.com
TENANT_ID=<tenant-guid>
# 任意（ソリューション運用する場合）
SOLUTION_NAME=SampleSolution
PUBLISHER_PREFIX=geek
# create_agent.py 用パラメータ
AGENT_NAME=my-new-agent
AGENT_SCHEMA=geek_mynewagent
AGENT_MODEL_SERIES=Sonnet46
# set_icon.py 用（任意）
ICON_TEXT=A
ICON_BG_COLOR=#2563EB
ICON_ACCENT_COLOR=#22C55E
