copilot-studio-v2 · git:20260904.49b41d5 · 2026-09-04 · sha256 04cc2dae42049ec8
copilot-studio-v2 git:20260904.49b41d5A

Name: copilot-studio-v2
Author: geekfujiwara
Immutable. This exact content is served forever at /api/v1/blob/04cc2dae42049ec8.
---
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"
  - "モデルは廃止されました"
  - "claude-opus-5"
  - "エージェント v2"
  - "エージェント アイコン"
  - "Dataverse MCP"
  - "Work IQ"
  - "PvaPublish"
  - "エージェント 公開"
  - "推奨プロンプト"
  - "初期メッセージ"
  - "greetingText"
  - "conversationStarters"
---

# 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`（例 `claude-opus-5`） |
| 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 でダウンロード不可）
   - 初期メッセージ（greeting）と推奨プロンプトを agent/prompts.json に用意し、AGENT_PROMPTS_FILE で指定する
3. scripts/create_agent.py     … cliagent Bot を API 作成 + プロビジョニング待ち
                                 （AGENT_PROMPTS_FILE があれば初期メッセージ・推奨プロンプトもここで設定）
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 で Build ＞ Model の表示を確認 … 「廃止されたモデル」なら scripts/set_model.py で修正し再公開
11. UI で MCP サーバーを追加（Dataverse / Work IQ 等）… ★手動作業（後述）
12. Preview で動作テスト（ユーザー）
```

> **一括実行**: 上記 3〜7 は [scripts/deploy_agent.py](scripts/deploy_agent.py) で
> ワンショット実行できる（`.env` の構成に従い作成→アイコン→Edit details→スキル→公開を連結）。
> MCP サーバーの追加は自動化対象外のため、この一括実行には含まれない。

## 運用中エージェントの更新（★新規作成しない）

`deploy_agent.py` は `create_agent.py` から始まるため、**実行するたびに新しい Bot が作られる**。
すでに UI で MCP ツールを追加した運用中のエージェントを更新するときは
[scripts/update_agent.py](scripts/update_agent.py) を使う。

```
1. set_instructions.py … Instructions を差し替え（configuration を GET → deep-merge → PATCH）
2. set_model.py        … モデル系列を差し替え（AGENT_MODEL_SERIES 指定時のみ）
3. set_prompts.py      … 初期メッセージ・推奨プロンプトを差し替え（指定時のみ）
4. attach_skill.py     … 同名スキルだけを入れ替え
5. publish_agent.py    … 再公開
```

```bash
python update_agent.py                # 全ステップ
python update_agent.py --no-publish   # 公開せず確認のみ
python update_agent.py --skip-skill   # スキルは触らない
```

### 手動追加したツール（MCP）が消えない理由

| 更新対象 | 保存先 | ツールへの影響 |
|---|---|---|
| Instructions / モデル / メモリ / 初期メッセージ / 推奨プロンプト | `bots.configuration`（JSON 文字列カラム） | **なし**（別レコード） |
| フラット Python スキル | `botcomponents` type=9 + 子 type=14 | **なし**（`attach_skill.py` は `name eq '<SKILL_NAME>' and componenttype eq 9` で絞って削除する） |
| MCP ツール | `botcomponents` type=9（`data` が `kind: McpTool`、接続参照を保持） | 上記のどれも触らない |

守るべき点は 2 つ。

- `configuration` は**丸ごと上書きせず GET → deep-merge → PATCH**（`name` 列を同送）。
  `set_instructions.py` / `set_model.py` / `set_prompts.py` は送信直前に
  [scripts/verify_config.py](scripts/verify_config.py) で他のキーが欠落していないか検証し、
  消失を検知したら PATCH を中止する。
- `attach_skill.py` の削除は**同名スキル限定**。`componenttype eq 9` だけで一括削除してはいけない
  （MCP ツールも type=9 のため、全消しすると接続参照ごと消える）。

`update_agent.py` は更新の前後で MCP ツールの schemaname と接続参照をスナップショットして差分を
表示し、**消失を検知したら公開せずに異常終了する**。

> 実機検証（MCP ツールを UI で追加済みのエージェント）:
> Instructions 更新 + スキル全ファイル再添付 + 再公開を実行しても、MCP ツールの schemaname と
> `connectionReference` は同一のまま維持された。

## 初期メッセージと推奨プロンプト

UI の「設定 ＞ Greeting & prompts」に相当する設定も `bots.configuration` に入る。

```jsonc
"agentSettings": {
  "greetingText": "こんにちは。〇〇エージェントです。",          // 初期メッセージ
  "conversationStarters": [                                      // 推奨プロンプト
    { "$kind": "ConversationStarter", "title": "進捗を確認", "text": "今月の進捗は？" }
  ]
}
```

- 未設定だと Teams / M365 側で `Hello! I'm <名前>. How can I help you today?` という既定文が出る。
- `AGENT_PROMPTS_FILE`（JSON）を `.env` に置けば、`create_agent.py` が**初回作成の時点で**
  configuration に含めるため、後からの手当ては不要。
- 運用中エージェントの差し替えは [scripts/set_prompts.py](scripts/set_prompts.py)
  （`--show` / `--file` / `--clear`）。`update_agent.py` からも自動で呼ばれる。
- 反映には**再公開**が必要。

```jsonc
// agent/prompts.json
{
  "greeting": "こんにちは。〇〇エージェントです。",
  "prompts": [{ "title": "進捗を確認", "text": "今月の進捗は？" }]
}
```

### MCP サーバーの追加は Copilot Studio UI での手動作業（重要）

MCP サーバー（Dataverse MCP / Work IQ 等）のツール追加は、**Copilot Studio UI から手動で行う**
前提とする。以前は Dataverse Web API（botcomponent type=9 の McpTool）で自動追加する手順を
提供していたが、接続参照の命名規約・公開後の「確認(Confirm)」操作など UI 側の状態に依存する
挙動が多く、API 経由での自動化は事故りやすい。そのため本スキルでは MCP ツール追加を
**スクリプト化しない**。詳細な手動手順は [MCP サーバーの追加](references/mcp-servers.md) を参照。

> **自前の MCP Server を作る場合**（社内 DB・ファイル共有・業務 API をエージェントに繋ぐ）は
> [mcp-server スキル](../mcp-server/SKILL.md) で構築してから、ここでツールとして追加する。

## 必須要件・落とし穴（実機検証済み）

### 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

```json
{
  "$kind": "BotConfiguration",
  "channels": [{ "$kind": "ChannelDefinition", "id": "MsTeams", "channelId": "MsTeams" }],
  "recognizer": { "$kind": "CLICopilotRecognizer" },
  "agentSettings": {
    "$kind": "AgentSettings",
    "model": { "$kind": "ModelConfig", "series": "claude-opus-5" },
    "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](references/flat-python-skill.md)）。

### スキルは「フラット Python バンドル」

新ランタイムの制約（実機で確認）:

```
❌ JavaScript / pptxgenjs は拒否される        → ✅ Python（python-pptx 等）のみ
❌ バンドル内のサブフォルダ階層は解決されない → ✅ フラット（同一階層に全ファイル）
❌ 同梱画像ファイルが読み込まれないことがある → ✅ 画像は assets_b64.py に Base64 埋め込み
```

詳細は [フラット Python スキルの書き方](references/flat-python-skill.md) を参照。

### スキルバンドルの 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` でアップロード

詳細は [スキルバンドル構造](references/skill-bundle-structure.md) を参照。

### アイコン・公開（実機検証済み）

```
✅ アイコンは bots.iconbase64(240) ＋ teams.colorIcon(192)/outlineIcon(32) の 3 か所へ登録
   ⚠ bots を PATCH する際は name 列を必ず同送（無いと 0x80040265 エラー）
✅ 公開は PvaPublish。状態確認は pac copilot list（publishedon は None のことがある）
```

MCP サーバーの追加は API 自動化の対象外（UI での手動作業）。手順は
[MCP サーバーの追加](references/mcp-servers.md) を参照。

詳細は [アイコン登録と公開](references/icon-and-publish.md) を参照。

### よくあるエラー

異常系（症状→原因→対処の一覧）は [references/troubleshooting.md](references/troubleshooting.md) を参照。

## スクリプト一覧

| スクリプト | 用途 |
|---|---|
| [scripts/create_agent.py](scripts/create_agent.py) | cliagent Bot を API 作成 + プロビジョニング待ち（廃止モデル名は作成前に弾く） |
| [scripts/set_model.py](scripts/set_model.py) | モデル系列の確認（`--show`）と変更（GET → deep-merge → PATCH） |
| [scripts/set_instructions.py](scripts/set_instructions.py) | Instructions の確認（`--show`）と差し替え（`--file` でファイル指定） |
| [scripts/set_prompts.py](scripts/set_prompts.py) | 初期メッセージ（greetingText）と推奨プロンプト（conversationStarters）の確認・設定・削除 |
| [scripts/set_icon.py](scripts/set_icon.py) | アイコン登録（iconbase64 / Teams color / outline） |
| [scripts/set_app_details.py](scripts/set_app_details.py) | Edit details 設定（PVA ゲートウェイ）。アイコン・説明文・開発元・リンク・MPN・store表示・Teams scopes・通話・SSO・M365 有効化。未設定はデフォルト補完 |
| [scripts/attach_skill.py](scripts/attach_skill.py) | フラット Python スキルを添付（type=9 + type=14） |
| [scripts/publish_agent.py](scripts/publish_agent.py) | PvaPublish で公開（リトライ付き） |
| [scripts/deploy_agent.py](scripts/deploy_agent.py) | 一括: 作成（初期メッセージ・推奨プロンプト込み）→アイコン→Edit details→スキル→公開 を連結（MCP は含まない・UI で手動追加） |
| [scripts/update_agent.py](scripts/update_agent.py) | 一括: **既存**エージェントを Instructions→モデル→推奨プロンプト→スキル→公開 で更新。MCP ツールの保全を前後差分で検証 |
| [scripts/verify_config.py](scripts/verify_config.py) | `configuration` の PATCH 直前に、更新対象以外のキー（model / instructions / memory / greeting 等）が消えていないか検証する共通ガード |
| [scripts/verify_agent.py](scripts/verify_agent.py) | 構造検証（filedata 実体ダウンロード確認） |
| [scripts/analyze_agent.py](scripts/analyze_agent.py) | 既存エージェントの構成・コンポーネントをダンプ |

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

## サブリファレンス

| リファレンス | 内容 |
|---|---|
| [新アーキテクチャ構造](references/new-architecture.md) | cliagent の BotConfiguration / botcomponents 全体像と v1 との対比 |
| [モデル系列の指定](references/model-series.md) | `agentSettings.model.series` の現行命名・廃止値・確認方法・後からの変更 |
| [フラット Python スキルの書き方](references/flat-python-skill.md) | JS 不使用・Base64 画像・フラット構成の実装テンプレート |
| [スキルバンドル構造](references/skill-bundle-structure.md) | type=9/14・親バインド・filedata アップロードの詳細 |
| [MCP サーバーの追加](references/mcp-servers.md) | Copilot Studio UI での MCP サーバー追加手順（手動作業） |
| [アイコン登録と公開](references/icon-and-publish.md) | iconbase64/Teams アイコン・PvaPublish・name 同送の注意 |
| [Edit details(チャネル メタデータ)](references/app-details.md) | Publish の Edit details を保存する PVA ゲートウェイ API・ペイロード対応・アイコン要件・ドラフト→公開 |

## .env 必須項目

`.env.example` は [references/.env.example](references/.env.example) を参照。

```env
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=claude-opus-5
# set_icon.py 用（任意）
ICON_TEXT=A
ICON_BG_COLOR=#2563EB
ICON_ACCENT_COLOR=#22C55E
```