copilot-studio git:20260907.8f60d9aA

Immutable. This exact content is served forever at /api/v1/blob/e9df68c5514ef273.

---
name: copilot-studio
description: "Copilot Studio エージェントの構築・設定・外部トリガー追加・ニュース配信エージェント等のソリューション構築。生成オーケストレーション（Generative Orchestration）モード一択。"
category: automation
triggers:
  - "Copilot Studio"
  - "エージェント作成"
  - "生成オーケストレーション"
  - "Instructions"
  - "指示"
  - "ナレッジ"
  - "MCP Server"
  - "PvaPublish"
  - "ボット設定"
  - "エージェント公開"
  - "Copilot Studio トリガー"
  - "メール受信"
  - "エージェント自動起動"
  - "ExecuteCopilot"
  - "Power Automate トリガー"
  - "Office 365 Outlook"
  - "メールトリガー"
  - "自動リサーチ"
  - "レポート自動生成"
  - "RSS"
  - "Web検索"
  - "定期配信"
  - "スケジュールトリガー"
  - "Work IQ MCP"
  - "ニュースエージェント"
  - "外部公開"
  - "Web埋め込み"
  - "認証なし"
  - "静的Webサイト"
  - "WebChat SDK"
  - "デザインテンプレート"
  - "外部Webデザイン"
  - "ランディングページ"
---

# Copilot Studio エージェント構築スキル

Copilot Studio エージェントを **生成オーケストレーション（Generative Orchestration）モード一択** で構築する。
外部トリガー・ニュース配信エージェント等の応用パターンまでカバーする統合スキル。

> **構築を始める前に**: [admin スキル](../admin/SKILL.md) で環境チェックと DLP 事前チェックを実行する。
> エージェントが使うコネクタ（Dataverse / カスタムコネクタ / MCP Server 等）が DLP でブロックされていたり、
> Business / Non-business が混在していると、公開時に「data loss prevention policy によりブロック」となり
> ツール構成からやり直しになる。

## サブリファレンス（必要に応じて参照）

| リファレンス | 内容 |
|---|---|
| [admin スキル（環境・DLP チェック）](../admin/SKILL.md) | 構築前の環境チェックと DLP 事前チェック、カスタムコネクタの DLP 分類変更 |
| [構築リファレンス](references/build-reference.md) | 構築手順の詳細・Instructions テンプレート・スクリプトコード |
| [**外部公開 WebChat SDK（標準）**](references/webchat-sdk-embed.md) | **外部公開の標準パターン**。BotFramework WebChat SDK で UI フルカスタマイズ・プログラム的メッセージ送信 |
| [**外部公開デザインテンプレート（標準 UI）**](references/webchat-sdk-design-template.md) | **標準 UI デザイン**：左パネル（カテゴリ別カード＋プロンプトチップス）＋ 右 WebChat パネル（グラデーション枠・AI タイピング Tips） |
| [**ライトモード・テンプレート集**](references/webchat-sdk-light-templates.md) | **ライトモード 5 レイアウト**（workspace / minimal / hero-cards / dashboard / sidebar）＋ 全テンプレート標準の**「新しい会話（初期化）」ボタン**（React 再マウント対策 `freshWebchatEl()`） |
| [外部公開 手動認証（SSO）](references/webchat-sdk-manual-auth.md) | Entra ID サインイン必須＋**ユーザー権限で Dataverse アクセス（RLS/OBO）**。2 アプリ登録・FIC（シークレットレス）・OAuth カードの silent トークン交換 |
| [外部公開 iframe（レガシー・非推奨）](references/external-web-embed.md) | iframe で埋め込む簡易版。UI カスタマイズ不可のため**標準では使わない**。動作確認・PoC 用のみ |
| [外部トリガー](references/trigger.md) | メール受信・Teams メッセージ・スケジュール等のトリガー追加 |
| [トリガーパターン](references/trigger-patterns.md) | トリガーの設定パターン集 |
| [トラブルシューティング](references/troubleshooting.md) | トリガー関連を中心とした異常系・トラブルシューティング |
| [ニュース配信エージェント](references/market-research-report.md) | RSS + Web検索 + Work IQ MCP によるニュース収集・配信エージェント構築 |
| [ニュース配信デプロイガイド](references/market-research-deployment-guide.md) | ニュース配信エージェントのデプロイ手順 |
| [ニュース配信メールテンプレート](references/market-research-email-template.md) | ニュース配信メールの HTML テンプレート |
| [トランスクリプト分析](references/transcript-analytics.md) | 会話トランスクリプトの分析パターン（ボット識別・ユーザー識別） |

## 外部公開 Web サイト開発フロー（必須）

**外部公開は WebChat UI（BotFramework WebChat SDK）を標準とする。** iframe 埋め込みは
UI カスタマイズができないためレガシー扱いとし、PoC・動作確認以外では使わない。

**WebChat UI のデザインは既存のデザインテンプレートを再利用する**
（新規にゼロからデザインを起こさない）:

- 標準（ダーク UI）: [webchat-sdk-design-template.md](references/webchat-sdk-design-template.md)
- ライトモード / 複数レイアウト: [webchat-sdk-light-templates.md](references/webchat-sdk-light-templates.md)

フロー:
1. **前提**: エージェントを「認証なし」で公開しておく
   （[set_agent_security.py](scripts/set_agent_security.py) を `AGENT_AUTH_MODE=none` で実行 → 公開）。
   WebChat SDK は「認証なし」エージェントの DirectLine トークンで匿名接続する。
2. 既存デザインテンプレートのレイアウト構成 + カテゴリ/プロンプト案をユーザーに提示
3. ユーザー承認
4. `website/index.html` を**既存テンプレートベース**で実装（WebChat SDK 埋め込み）
5. カテゴリ・プロンプト・Tips・カラーを案件に合わせて調整
6. `py scripts/deploy_website.py` で Azure Storage にデプロイ

> ⚠️ 「認証なし」の設定は [構築リファレンスの Step 7-8](references/build-reference.md) の
> 3 スクリプト分離フロー（構築 → セキュリティ → チャネル）に従うこと。認証モードを設定せず
> 公開すると UI 既定の **Microsoft 認証** になり、WebChat SDK が匿名接続できない。

## 前提: 設計フェーズ完了後に構築に入る（必須）

**エージェントを構築する前に、エージェント設計をユーザーに提示し承認を得ていること。**

設計提示時に含める内容:

| 項目                     | 内容                                                                          |
| ------------------------ | ----------------------------------------------------------------------------- |
| エージェント名・説明     | 名前と役割の説明                                                              |
| Instructions             | 指示テキストの全文案                                                          |
| 推奨プロンプト           | 3〜5 個のタイトル＋プロンプト文（GPT コンポーネントの conversationStarters）  |
| 会話の開始のメッセージ   | エージェントに合った挨拶テキスト（ConversationStart トピックの SendActivity） |
| 会話の開始のクイック返信 | 3〜5 個のクイック返信テキスト（ConversationStart トピックの quickReplies）    |
| ナレッジ                 | データソース（Dataverse テーブル / SharePoint / ファイル等）                  |
| ツール                   | MCP Server の接続先・用途                                                     |
| チャネル公開設定         | 簡単な説明・詳細な説明・背景色・開発者名（デフォルト値を提案）                |

```
フロー: 設計提示 → ユーザー承認 → アイコン画像提案 → ユーザー選択 → UI で Bot 作成 → スクリプトで設定適用
```

## アイコン画像提案（設計承認後・構築前）

> **アイコンの設計・生成・登録の詳細は `standard` スキルの [アイコン作成リファレンス](../standard/references/icon-creation.md) を参照。**
> ここではエージェント固有の手順のみ記載する。

エージェント設計が承認されたら、**Bot 作成前にアイコン画像を提案**する。
`standard` スキルの [アイコン作成リファレンス](../standard/references/icon-creation.md) のアイコン画像提案フローに従い、3〜4 パターンを提案 → ユーザー選択 → PNG 3 サイズ生成（240, 192, 32）→ `bots.iconbase64` + Teams マニフェストに API 登録。

## 大前提: 一つのソリューション内に開発

Dataverse テーブル・Code Apps・Power Automate フロー・Copilot Studio エージェントは **すべて同一のソリューション内** に含める。

```
SOLUTION_NAME=SampleSolution  ← .env で定義。全フェーズで同じ値を使用
PUBLISHER_PREFIX=geek              ← ソリューション発行者の prefix
```

- API ヘッダーに `MSCRM.SolutionName: {SOLUTION_NAME}` を付けることでソリューション内に作成

> **認証**: Python スクリプトの認証は `standard` スキルの `auth_helper.py` を使用。
> `from auth_helper import get_token, get_session, api_get, api_post, api_patch` で利用する。

- Bot 作成時（Copilot Studio UI）は「エージェント設定」でソリューションを明示的に選択
- ソリューション外で作成したコンポーネントはリリース管理・環境間移行ができない

## 必須要件

### Bot 作成は API 不可 → Copilot Studio UI 必須

```
❌ Dataverse bots テーブルへの直接 INSERT
   → PVA Bot Management Service にプロビジョニングされない
   → Copilot Studio UI で「エージェントの作成中に問題が発生しました」エラー
   → botroutinginfo が 404 になる

✅ Copilot Studio UI で手動作成 → API で設定変更のみ
```

### GPT コンポーネント（componenttype=15）の扱い

1. **UI が作成したコンポーネントを特定して更新する**
   - `bots(id)?$select=configuration` → `configuration.gPTSettings.defaultSchemaName` で UI コンポーネントの schemaname を取得
   - API で新しい GPT コンポーネントを INSERT すると UI と API で別々のコンポーネントが存在し、UI は自分のコンポーネントしか読まない

2. **configuration を PATCH する際は既存値をディープマージする**
   - `configuration` を丸ごと上書きすると `gPTSettings.defaultSchemaName` やモデル設定が消える
   - 必ず GET → ディープマージ → PATCH
   - `optInUseLatestModels` は明示的に `False` を設定 — `True` だと UI で選択した基盤モデル（Claude Sonnet 等）が GPT に強制変更される
   - `aISettings` も丸ごと上書きせずディープマージで既存のモデル選択を保持

3. **余分な GPT コンポーネントは削除する**
   - `componenttype eq 15` で全取得 → `defaultSchemaName` と一致するものを UI コンポーネントとして特定 → それ以外を削除

### 指示（Instructions）の YAML 形式 — PVA ダブル改行フォーマット

PVA パーサーは標準 YAML のシングル改行 (`\n`) を**構造行**として認識しない。
YAML の**構造行**（kind, displayName, conversationStarters 等）はダブル改行 (`\n\n`) で区切る必要がある。
ただし `instructions: |-` ブロック内のテキストはシングル改行で記述する。

```python
# ✅ 正しい構築方法
def _build_gpt_yaml():
    # instructions ブロック（シングル改行）
    inst_block = "\n".join(f"  {line}" for line in GPT_INSTRUCTIONS.splitlines())

    # conversationStarters（ダブル改行）
    starter_lines = []
    for p in PREFERRED_PROMPTS:
        starter_lines.append(f"  - title: {p['title']}")
        starter_lines.append(f"    text: {p['text']}")
    starters_block = "\n\n".join(starter_lines)

    return (
        "kind: GptComponentMetadata\n\n"
        f"displayName: {BOT_NAME}\n\n"
        f"instructions: |-\n{inst_block}\n\n"
        f"conversationStarters:\n\n{starters_block}\n\n"
    )
```

```
❌ yaml.dump() → PVA パーサーと非互換
❌ 全行シングル改行 → conversationStarters / quickReplies が UI に反映されない
❌ 全行ダブル改行 → instructions テキストが空行だらけになる
❌ conversationStarters の title/text をダブルクォートで囲む → PVA に反映されない
✅ 構造行はダブル改行、instructions ブロック内はシングル改行
✅ conversationStarters の title/text はクォートなし
✅ displayName キーを含める（UI が表示に使用）
✅ instructions 内で単一波括弧 {変数名} を使わない → PVA が Power Fx 式として解釈し IdentifierNotRecognized エラー。自然言語で記述する
```

### ConversationStart トピックの YAML 形式

ConversationStart トピック（componenttype=9）も同じダブル改行フォーマット。

```python
lines = []
lines.append("kind: AdaptiveDialog")
lines.append("beginDialog:")
lines.append("  kind: OnConversationStart")
lines.append("  id: main")
lines.append("  actions:")
lines.append("    - kind: SendActivity")
lines.append(f"      id: {send_id}")
lines.append("      activity:")
lines.append("        text:")
lines.append(f"          - {greeting_text}")  # クォートなし
lines.append("        speak:")
lines.append(f'          - "{greeting_text}"')
lines.append("        quickReplies:")
for qr in QUICK_REPLIES:
    lines.append(f"          - kind: MessageBack")
    lines.append(f"            text: {qr}")
# ダブル改行で結合
new_data = "\n\n".join(lines) + "\n\n"
```

```
❌ シングル改行 → 送信ノードが消え、quickReplies が UI に反映されない
❌ 挨拶テキストに生改行 \n を含める → YAML が壊れる（スペースに置換する）
✅ 全行ダブル改行で結合
✅ actions 配下は 4 スペースインデント
```

### 基盤モデル選択の保持（aISettings）

PVA は GPT コンポーネントの `data` YAML 末尾に基盤モデル情報を格納する:

```yaml
aISettings:
  model:
    modelNameHint: Sonnet46
```

GPT コンポーネントの `data` を上書きすると、この `aISettings` セクションが消えて
デフォルトモデル（GPT 4.1）に戻る。

```python
# ✅ 更新前に既存データから aISettings セクションを抽出 → 新 YAML の末尾に付加
existing_data = ui_comp.get("data", "")
ai_idx = existing_data.find("\naISettings:")
if ai_idx < 0:
    ai_idx = existing_data.find("aISettings:")
if ai_idx >= 0:
    ai_settings_section = existing_data[ai_idx:].rstrip()
    final_yaml = new_yaml.rstrip("\n") + "\n\n" + ai_settings_section + "\n\n"
```

```
❌ GPT data を丸ごと上書き → 基盤モデルがデフォルトに戻る
✅ 更新前に aISettings セクションを抽出して保持
✅ 初回デプロイ後にユーザーが UI でモデルを設定 → 2 回目以降のデプロイで保持される
```

### 説明（Description）の保存場所

```
❌ YAML 内の description キー → UI が読まない
❌ bot エンティティの description プロパティ → 存在しない
✅ botcomponents テーブルの description カラム

注意: data PATCH の非同期処理が description を上書きする
→ 対策: publish 後に description を別途 PATCH する
```


## 構築手順

詳細な構築手順・スクリプトコードは [構築リファレンス](references/build-reference.md) を参照。

> **設計承認と同時に並行着手（VS Code サブエージェント）**: Phase 1 の設計承認後、Dataverse 構築を待たずに
> 本トラック（Copilot Studio）を**並行して開始**できる。VS Code では Copilot Studio サブエージェントとして起動する。
> **先行工程（テーブル不要）** = Bot 作成 → 生成オーケストレーション有効化 → Instructions 設定（Step 0–4）は
> Dataverse 構築と完全に並行で進められる。以下は Dataverse／Power Automate の完了を待つ**同期点**:
> - **★同期①（テーブル作成完了後）** — Dataverse をソースにするナレッジ／MCP の追加（Step 9）。
> - **★同期②（フロー作成完了後）** — Power Automate フローをツール化する連携。
>
> 全体のトラック分割・オーケストレーションは [standard §8「開発フロー全体図」](../standard/references/power-platform-development-standard.md#8-開発フロー全体図) を参照。

高レベルの手順:

1. **Step 0**: Copilot Studio UI で Bot 作成（ユーザー手動）
2. **Step 1-1.5**: Bot 検索 + プロビジョニング完了待ち
3. **Step 2**: カスタムトピック削除（システムトピック保護）
4. **Step 3**: 生成オーケストレーション有効化
5. **Step 4-4.5**: Instructions + 会話の開始設定
6. **Step 5-6**: エージェント公開 + 説明設定（`deploy_agent.py` はここまで）
7. **Step 7**: セキュリティ（認証モード）設定 → 公開（`set_agent_security.py`）
8. **Step 8**: チャネル選択（Web/Teams/Copilot）→ 公開（`set_agent_channels.py`）
9. **Step 9**: ナレッジ・ツール・トリガーの手動追加案内

> **⚠️ 「公開」処理は 3 スクリプトに分離する（一体化禁止）**
>
> セキュリティ設定 → 公開 → チャネル選択 → 公開 を 1 本のスクリプトにまとめると、
> 認証モードを設定し忘れて UI 既定の **Microsoft 認証** で公開され、Web 埋め込みができなくなる。
> 必ず以下の順で実行する:
>
> | 順 | スクリプト | 役割 | 主な .env |
> |---|---|---|---|
> | 1 | `deploy_agent.py` | 構築（Step 1–6）＋公開 | — |
> | 2 | `set_agent_security.py` | 認証モード設定→公開 | `AGENT_AUTH_MODE`（`none` / `microsoft`） |
> | 3 | `set_agent_channels.py` | チャネル選択→公開 | `AGENT_CHANNELS`（`web,teams,copilot`） |
>
> `bots.authenticationmode`: `2`=認証なし（Web 埋め込み必須）／`1`=Microsoft で認証（UI 既定・Teams）。
> 認証変更は**公開後に反映**される。

Instructions テンプレート・既存エージェント改善パターンは [構築リファレンス](references/build-reference.md#instructions-テンプレート) を参照。

## .env 必須項目

全パラメータの定義（取得元コメント付き）は [references/.env.example](references/.env.example) を参照。
実値はリポジトリルートの `.env` に置く（`.gitignore` 済み）。

```env
DATAVERSE_URL=https://{org}.crm.dynamics.com/
SOLUTION_NAME=SolutionName
PUBLISHER_PREFIX=prefix
BOT_ID=https://copilotstudio.../bots/xxxxxxxx-xxxx-.../overview
# ↑ Copilot Studio URL をそのまま貼り付け可。GUID だけでも OK
```