copilot-studio-v2

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 列	[e-mail] → /bots(...)
14	FileAttachmentComponent（同梱ファイル）	filedata File 列	[e-mail] → /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 を参照。

スクリプト一覧

スクリプト	用途
scripts/create_agent.py	cliagent Bot を API 作成 + プロビジョニング待ち
scripts/set_icon.py	アイコン登録（iconbase64 / Teams color / outline）
scripts/set_app_details.py	Edit details 設定（PVA ゲートウェイ）。アイコン・説明文・開発元・リンク・MPN・store表示・Teams scopes・通話・SSO・M365 有効化。未設定はデフォルト補完
scripts/attach_skill.py	フラット Python スキルを添付（type=9 + type=14）
scripts/publish_agent.py	PvaPublish で公開（リトライ付き）
scripts/deploy_agent.py	一括: 作成→アイコン→Edit details→スキル→公開 を連結（MCP は含まない・UI で手動追加）
scripts/verify_agent.py	構造検証（filedata 実体ダウンロード確認）
scripts/analyze_agent.py	既存エージェントの構成・コンポーネントをダンプ

認証: 全スクリプトは standard スキルの auth_helper.py を使用する（requests 直呼び禁止）。

サブリファレンス

リファレンス	内容
新アーキテクチャ構造	cliagent の BotConfiguration / botcomponents 全体像と v1 との対比
フラット Python スキルの書き方	JS 不使用・Base64 画像・フラット構成の実装テンプレート
スキルバンドル構造	type=9/14・親バインド・filedata アップロードの詳細
MCP サーバーの追加	Copilot Studio UI での MCP サーバー追加手順（手動作業）
アイコン登録と公開	iconbase64/Teams アイコン・PvaPublish・name 同送の注意
Edit details(チャネル メタデータ)	Publish の Edit details を保存する PVA ゲートウェイ API・ペイロード対応・アイコン要件・ドラフト→公開

.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