Copilot Studio エージェント構築スキル
Copilot Studio エージェントを 生成オーケストレーション（Generative Orchestration）モード一択 で構築する。
外部トリガー・ニュース配信エージェント等の応用パターンまでカバーする統合スキル。
構築を始める前に: admin スキル で環境チェックと DLP 事前チェックを実行する。
エージェントが使うコネクタ（Dataverse / カスタムコネクタ / MCP Server 等）が DLP でブロックされていたり、
Business / Non-business が混在していると、公開時に「data loss prevention policy によりブロック」となり
ツール構成からやり直しになる。
サブリファレンス（必要に応じて参照）
事前確認（会話の最初に 1 回だけ）
本スキルの利用が確定したら、standard の共通契約に加え、
1 回の AskUserQuestion で次をまとめて確認する。
| # | 質問 | 合格条件 |
|---|
| 1 | v1 が必要な利用形態か | Code Apps 連携、WebChat、外部トリガー等の v1 採用理由が明確である |
| 2 | 対象環境で作成・公開できるか | Copilot Studio の必要ライセンス / capacity と maker / publish 権限がある |
| 3 | channel と audience は何か | Teams / M365 Copilot / Web、internal / external / anonymous、公開担当者が確定している |
| 4 | 認証とデータアクセスは何か | Microsoft 認証 / manual auth / none、Dataverse RLS、接続所有者を承認済みである |
| 5 | knowledge、MCP、trigger、外部文章を使うか | 接続権限、送信データ、prompt injection 対策、実害操作の確認方法が確定している |
| 6 | エージェント設計とテスト範囲は承認済みか | Instructions、モデル、ツール、アイコン、テストユーザー、期待応答を記録している |
外部公開で AGENT_AUTH_MODE=none を使う場合は、匿名アクセスで公開してよいデータと操作を
明示承認する。ライセンス、認証方式、公開対象のいずれかが未確認なら公開しない。
外部公開 Web サイト開発フロー（必須）
外部公開は WebChat UI（BotFramework WebChat SDK）を標準とする。 iframe 埋め込みは
UI カスタマイズができないためレガシー扱いとし、PoC・動作確認以外では使わない。
WebChat UI のデザインは既存のデザインテンプレートを再利用する
（新規にゼロからデザインを起こさない）:
フロー:
- 前提: エージェントを「認証なし」で公開しておく
（set_agent_security.py を
AGENT_AUTH_MODE=none で実行 → 公開）。
WebChat SDK は「認証なし」エージェントの DirectLine トークンで匿名接続する。
- 既存デザインテンプレートのレイアウト構成 + カテゴリ/プロンプト案をユーザーに提示
- ユーザー承認
website/index.html を既存テンプレートベースで実装（WebChat SDK 埋め込み）- カテゴリ・プロンプト・Tips・カラーを案件に合わせて調整
py scripts/deploy_website.py で Azure Storage にデプロイ
⚠️ 「認証なし」の設定は 構築リファレンスの Step 7-8 の
3 スクリプト分離フロー（構築 → セキュリティ → チャネル）に従うこと。認証モードを設定せず
公開すると UI 既定の Microsoft 認証 になり、WebChat SDK が匿名接続できない。
前提: 設計フェーズ完了後に構築に入る（必須）
エージェントを構築する前に、エージェント設計をユーザーに提示し承認を得ていること。
設計提示時に含める内容:
| 項目 | 内容 |
|---|
| エージェント名・説明 | 名前と役割の説明 |
| Instructions | 指示テキストの全文案 |
| 推奨プロンプト | 3〜5 個のタイトル＋プロンプト文（GPT コンポーネントの conversationStarters） |
| 会話の開始のメッセージ | エージェントに合った挨拶テキスト（ConversationStart トピックの SendActivity） |
| 会話の開始のクイック返信 | 3〜5 個のクイック返信テキスト（ConversationStart トピックの quickReplies） |
| ナレッジ | データソース（Dataverse テーブル / SharePoint / ファイル等） |
| ツール | MCP Server の接続先・用途 |
| チャネル公開設定 | 簡単な説明・詳細な説明・背景色・開発者名（デフォルト値を提案） |
フロー: 設計提示 → ユーザー承認 → アイコン画像提案 → ユーザー選択 → UI で Bot 作成 → スクリプトで設定適用
アイコン画像提案（設計承認後・構築前）
アイコンの設計・生成・登録の詳細は standard スキルの アイコン作成リファレンス を参照。
ここではエージェント固有の手順のみ記載する。
エージェント設計が承認されたら、Bot 作成前にアイコン画像を提案する。
standard スキルの アイコン作成リファレンス のアイコン画像提案フローに従い、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）は「エージェント設定」でソリューションを明示的に選択
- ソリューション外で作成したコンポーネントはリリース管理・環境間移行ができない
必須要件
ツールにする Power Automate フローは kind: VirtualAgent（★ 検証済み教訓 2026-10-09）
エージェントのツールとして追加する Power Automate フローは、
トリガー・応答ともに kind: "VirtualAgent" でなければならない。
❌ トリガー "kind": "PowerAppV2" / 応答 "kind": "PowerApp"
→ フローのデプロイ・有効化は成功し Power Automate UI にも出るが、
「ツールを追加 → フロー」の一覧に**一切表示されない**
✅ トリガー {"type": "Request", "kind": "VirtualAgent"}
✅ 応答 {"type": "Response", "kind": "VirtualAgent"}
応答 schema は PowerApp 応答と形式が違う:
✅ プロパティは title + x-ms-dynamically-added のみ
❌ x-ms-content-hint / additionalProperties は付けない
★ フローを再デプロイすると workflow ID が変わる
→ 追加済みのツールは参照切れになるので削除 → 再追加する
実装の詳細は power-automate スキルの trigger-action-patterns.md
「Copilot Studio トリガー（VirtualAgent）」を参照。
Bot 作成は観測済みcontractで承認付き自動化
❌ name / schemanameだけの Dataverse bots INSERT
→ PVA Bot Management Service にプロビジョニングされない
→ Copilot Studio UI で「エージェントの作成中に問題が発生しました」エラー
→ botroutinginfo が 404 になる
✅ scripts/provision_agent.py plan でUI観測済みcontractとSHA-256を生成
✅ 承認したhashでapplyし、template/configuration/iconを含むPOSTを1回だけ実行
✅ componenttype 9（topic）と15（GPT）のread-back後に設定変更へ進む
GPT コンポーネント（componenttype=15）の扱い
-
UI が作成したコンポーネントを特定して更新する
bots(id)?$select=configuration → configuration.gPTSettings.defaultSchemaName で UI コンポーネントの schemaname を取得- API で新しい GPT コンポーネントを INSERT すると UI と API で別々のコンポーネントが存在し、UI は自分のコンポーネントしか読まない
-
configuration を PATCH する際は既存値をディープマージする
configuration を丸ごと上書きすると gPTSettings.defaultSchemaName やモデル設定が消える- 必ず GET → ディープマージ → PATCH
optInUseLatestModels は明示的に False を設定 — True だと UI で選択した基盤モデル（Claude Sonnet 等）が GPT に強制変更されるaISettings も丸ごと上書きせずディープマージで既存のモデル選択を保持
-
余分な GPT コンポーネントは削除する
componenttype eq 15 で全取得 → defaultSchemaName と一致するものを UI コンポーネントとして特定 → それ以外を削除
指示（Instructions）の YAML 形式 — PVA ダブル改行フォーマット
PVA パーサーは標準 YAML のシングル改行 (\n) を構造行として認識しない。
YAML の構造行（kind, displayName, conversationStarters 等）はダブル改行 (\n\n) で区切る必要がある。
ただし instructions: |- ブロック内のテキストはシングル改行で記述する。
# ✅ 正しい構築方法
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）も同じダブル改行フォーマット。
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 末尾に基盤モデル情報を格納する:
aISettings:
model:
modelNameHint: Sonnet46
GPT コンポーネントの data を上書きすると、この aISettings セクションが消えて
デフォルトモデル（GPT 4.1）に戻る。モデル変更はset_model.pyでplanを作り、承認したhashだけをapplyする。
python scripts/set_model.py show --bot-id $env:BOT_ID
python scripts/set_model.py plan --bot-id $env:BOT_ID --model $env:AGENT_MODEL_NAME
python scripts/set_model.py apply --expected-hash <承認したSHA-256>
❌ GPT data を丸ごと上書き → 基盤モデルがデフォルトに戻る
❌ componentが複数あるときに先頭を更新 → UI所有componentとずれる
✅ configuration.gPTSettings.defaultSchemaNameで所有componentを特定。無い場合はGPT componentが1件のときだけ続行
✅ 元YAML hashとETagを承認planへ束縛し、modelNameHint以外を保持
✅ PATCH後にYAML全体hashとmodelNameHintをread-back。反映には再公開が必要
説明（Description）の保存場所
❌ YAML 内の description キー → UI が読まない
❌ bot エンティティの description プロパティ → 存在しない
✅ botcomponents テーブルの description カラム
注意: data PATCH の非同期処理が description を上書きする
→ 対策: publish 後に description を別途 PATCH する
構築手順
詳細な構築手順・スクリプトコードは 構築リファレンス を参照。
設計承認と同時に並行着手（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「開発フロー全体図」 を参照。
高レベルの手順:
- Step 0:
provision_agent.pyでplan生成・hash承認・Botプロビジョニング
- Step 1-1.5: Bot 検索 + プロビジョニング完了待ち
- Step 2: カスタムトピック削除（システムトピック保護）
- Step 3: 生成オーケストレーション有効化
- Step 4:
set_model.pyでmodel plan生成・hash承認・apply
- Step 5-5.5: Instructions + 会話の開始設定
- Step 6-7: エージェント公開 + 説明設定（
deploy_agent.py はここまで）
- Step 8: セキュリティ（認証モード）設定 → 公開（
set_agent_security.py）
- Step 9: チャネル選択（Web/Teams/Copilot）→ 公開（
set_agent_channels.py）
- Step 10: Standard MCP toolを承認付きprivate APIで追加。connector tool・ナレッジ・トリガーは各contractに従う
⚠️ 「公開」処理は 3 スクリプトに分離する（一体化禁止）
セキュリティ設定 → 公開 → チャネル選択 → 公開 を 1 本のスクリプトにまとめると、
認証モードを設定し忘れて UI 既定の Microsoft 認証 で公開され、Web 埋め込みができなくなる。
必ず以下の順で実行する:
| 順 | スクリプト | 役割 | 主な .env |
|---|
| 1 | provision_agent.py | 承認付き初回プロビジョニング | AGENT_NAME, BOT_SCHEMA, AGENT_LANGUAGE, SOLUTION_NAME |
| 2 | set_model.py | 承認付き基盤モデル設定 | BOT_ID, AGENT_MODEL_NAME |
| 3 | deploy_agent.py | 構築（Instructions等）＋公開 | BOT_ID または AGENT_NAME |
| 4 | set_agent_security.py | 認証モード設定→公開 | AGENT_AUTH_MODE（none / microsoft） |
| 5 | set_agent_channels.py | チャネル選択→公開 | AGENT_CHANNELS（web,teams,copilot） |
Copilot Studio v1 の bots.authenticationmode: 1=認証なし（Web 埋め込み必須）／2=Microsoft で認証（UI 既定・Teams）。
認証変更は公開後に反映される。
Instructions テンプレート・既存エージェント改善パターンは 構築リファレンス を参照。
.env 必須項目
全パラメータの定義（取得元コメント付き）は references/.env.example を参照。
実値はリポジトリルートの .env に置く（.gitignore 済み）。
DATAVERSE_URL=https://{org}.crm.dynamics.com/
SOLUTION_NAME=SolutionName
PUBLISHER_PREFIX=prefix
AGENT_NAME=AgentName
AGENT_LANGUAGE=1041
BOT_SCHEMA=prefix_AgentName
BOT_ID=https://copilotstudio.../bots/xxxxxxxx-xxxx-.../overview
# ↑ Copilot Studio URL をそのまま貼り付け可。GUID だけでも OK
AGENT_MODEL_NAME=Sonnet46