| name | ai-builder |
| description | AI Builder の AI プロンプト（GPT Dynamic Prompt）を Dataverse API で作成し、Copilot Studio エージェントにツール（アクション）として追加する。Power Automate フローとの統合パターンも含む。 |
| category | ai |
| triggers | ["AI Builder","AI プロンプト","GPT Prompt","AIプロンプト作成","エージェントツール追加","msdyn_aimodel","InvokeAIBuilderModelTaskAction","プロンプトデプロイ","AI Prompt","aibuilderpredict","フロー AI Builder"] |
AI Builder AI プロンプト構築スキル
AI Builder の AI プロンプト（GPT Dynamic Prompt） を Dataverse API で作成し、
Copilot Studio エージェントに ツール（アクション） として追加する。
Power Automate フローから aibuilderpredict_customprompt で呼び出すパターンも含む。
基本方針: AI プロンプトを常にプレビルトモデルより優先する
AI Builder で AI 処理を実装する場合、以下の方針に従う:
✅ AI プロンプト（カスタムプロンプト）を常に第一選択肢とする
- 請求書処理、ドキュメント情報抽出、分類、要約 等すべて
- プロンプトテキスト + document/image 入力で柔軟に対応
- トレーニングデータ不要、即座にデプロイ・更新可能
- プロンプト変更だけで出力形式・抽出項目を自由に調整
❌ プレビルトモデル（請求書処理モデル等）は原則使用しない
- 従来型のプレビルトモデルやカスタムモデルはトレーニング（学習）が必要
- AI プロンプトで同等の処理がプロンプトだけで実現できる
⚠ プレビルトモデルを使う例外ケース（稀）
- 手書き文字の高精度 OCR が必須で AI プロンプトでは精度不足の場合
- 既存のプレビルトモデルが組み込まれたワークフローを維持する必要がある場合
前提: 設計フェーズ完了後に構築に入る（必須）
AI プロンプトを構築する前に、プロンプト設計をユーザーに提示し承認を得ていること。
設計提示時に含める内容:
| 項目 | 内容 |
|---|
| プロンプト名 | 英語推奨（スキーマ名に使用される） |
| プロンプトテキスト | リテラルテキスト＋入力変数の組み合わせ |
| 入力変数 | 名前・型（text / document / image）・説明・テスト値 |
| 出力形式 | text or json（JSON の場合はスキーマ＋サンプル） |
| モデルパラメータ | モデル種別（gpt-41-mini 等）・temperature |
| 利用先 | Copilot Studio ツール or Power Automate フロー |
| shouldPromptUser | 各入力変数をユーザーに自動的に尋ねるか（true/false） |
重要事項: AIModelPublish 1ステップ・アクティベーション
2026-04-15 検証済み: AIModelPublish アクションは1ステップでモデルを完全にアクティブ化する。
従来（旧パターン — ❌ 複雑で環境差異に弱い）:
1. Create Model
2. Create Training Config (statecode=2, statuscode=6 を指定)
3. Create Run Config (statecode=2, statuscode=7 を指定)
4. PATCH Model (_msdyn_activerunconfigurationid_value + statecode=1)
→ 環境によって statecode/statuscode 指定や _value PATCH が拒否される
正解（新パターン — ✅ シンプルで確実）:
1. Create Model（msdyn_TemplateId@odata.bind 形式）
2. AIModelPublish（msdyn_ プレフィックスなし unbound action）
→ Published Training Config (state=2, status=6) を自動生成
→ Run Config (state=2, status=7) を自動生成（RunConfigurationId の値が ID になる）
→ Model を Active (state=1, status=1) に自動変更
→ 完了! わずか 2 API コール
更新時:
1. 既存 Model を検索 → Active Run Config の ID を取得
2. Run Config の msdyn_customconfiguration を PATCH
→ 完了!（再公開不要）
AIModelPublish の呼び出し方
import requests
token = get_token()
headers = {
"Authorization": f"Bearer {token}",
"OData-MaxVersion": "4.0",
"OData-Version": "4.0",
"Content-Type": "application/json; charset=utf-8",
}
r = requests.post(
f"{DATAVERSE_URL}/api/data/v9.2/AIModelPublish",
headers=headers,
json={
"TemplateId": GPT_TEMPLATE_ID,
"ModelId": model_id,
"RunConfigurationId": model_id,
"ModelName": PROMPT_NAME,
"CustomConfiguration": custom_config_json_str,
"RunConfiguration": custom_config_json_str,
},
)
assert r.status_code < 400, f"AIModelPublish 失敗: {r.status_code}"
重要な注意点
| 項目 | 説明 |
|---|
| アクション名 | AIModelPublish（msdyn_AIModelPublish ではない! プレフィックスなし） |
| RunConfigurationId | model_id を渡すと Run Config がその ID で自動作成される |
| 自動生成物 | Published Training (state=2,status=6) + Run Config (state=2,status=7) |
| 結果 | Model が state=1（Active）に自動変更される |
| 副作用 | Published Training Config は DELETE 不可（405）→ 無害 |
| 失敗時 | 既に Active な Run Config がある場合 AnotherRunConfigAlreadyPublished |
Dataverse データ構造
AI Builder の AI プロンプトは 3 つの Dataverse テーブル + 1 つの botcomponent で構成される。
┌─────────────────────────┐
│ msdyn_aimodel │ ← AI プロンプト本体
│ (msdyn_aimodels) │
│ │
│ msdyn_name │ プロンプト名
│ _msdyn_templateid_value│ GPT Prompt テンプレート ID
│ _msdyn_activerunconfigurationid_value │ → Run Config
│ statecode=1 (Active) │
└──────────┬──────────────┘
│ 1:N
▼
┌─────────────────────────┐
│ msdyn_aiconfiguration │ ← 設定（AIModelPublish で自動生成）
│ (msdyn_aiconfigurations│
│ │
│ Training (type=190690000, state=2, status=6) │ Published Training
│ Run (type=190690001, state=2, status=7) │ Active Run Config
│ msdyn_customconfiguration = JSON │ ← プロンプト定義本体
└─────────────────────────┘
┌─────────────────────────┐
│ botcomponent │ ← エージェントとの紐付け（Copilot Studio 利用時のみ）
│ (botcomponents) │
│ │
│ componenttype=9 │ トピックと同じ型
│ kind: TaskDialog │ AI プロンプトアクション
│ action.aIModelId │ → msdyn_aimodel の GUID
│ _parentbotid_value │ → エージェント (bots)
└─────────────────────────┘
テンプレート ID（固定値）
| テンプレート名 | ID |
|---|
| GPT Dynamic Prompt | edfdb190-3791-45d8-9a6c-8f90a37c278a |
msdyn_customconfiguration の JSON 構造
{
"version": "GptDynamicPrompt-2",
"prompt": [
{ "type": "literal", "text": "以下の情報を分析してください: " },
{ "type": "inputVariable", "id": "input_text" },
{ "type": "literal", "text": " を基にレポートを作成。" }
],
"definitions": {
"inputs": [
{
"id": "input_text",
"text": "input_text",
"type": "text",
"quickTestValue": "テスト用のサンプルテキスト"
}
],
"formulas": [],
"data": [],
"output": {
"formats": ["json"],
"jsonSchema": {
"type": "object",
"properties": {
"summary": { "type": "string" },
"key_points": { "type": "array", "items": { "type": "string" } }
}
},
"jsonExamples": [
{ "summary": "出力例", "key_points": ["ポイント1", "ポイント2"] }
]
}
},
"modelParameters": {
"modelType": "gpt-41-mini",
"gptParameters": { "temperature": 0 }
},
"settings": {
"recordRetrievalLimit": 30,
"shouldPreserveRecordLinks": null,
"runtime": null
},
"code": "",
"signature": ""
}
prompt 配列の要素型
| type | 説明 | 必須フィールド |
|---|
literal | 固定テキスト | text |
inputVariable | 入力変数への参照 | id |
definitions.inputs の型
| type | 説明 | 備考 |
|---|
text | テキスト入力 | quickTestValue でテスト値 |
document | ドキュメント入力 | ファイルアップロード |
image | 画像入力 | 画像ファイル |
definitions.output の形式
| formats | 説明 | 追加フィールド |
|---|
["text"] | テキスト出力 | なし |
["json"] | JSON 出力 | jsonSchema + jsonExamples 必須 |
modelParameters.modelType の値
| 値 | モデル |
|---|
gpt-41-mini | GPT-4.1 mini |
gpt-41 | GPT-4.1 |
o3-mini | o3-mini |
botcomponent の YAML 構造（kind: TaskDialog）
kind: TaskDialog
inputs:
- kind: AutomaticTaskInput
propertyName: text
name: text
shouldPromptUser: true
modelDisplayName: AI Prompt Sample
modelDescription: AI Prompt Sample
action:
kind: InvokeAIBuilderModelTaskAction
aIModelId: {your-ai-model-id}
outputMode: All
構築手順
詳細な構築手順・デプロイスクリプトテンプレートは 構築リファレンス を参照。
Power Automate フローからの AI Builder 呼び出し
AI Builder プロンプトを Power Automate フロー内で呼び出す パターン。
Copilot Studio ツールではなく、Dataverse トリガー等と組み合わせて自動実行する場合に使う。
詳細は Power Automate 連携リファレンス を参照。
必須要件
AI Model 作成【必須】
✅ テンプレート ID は固定値 edfdb190-3791-45d8-9a6c-8f90a37c278a（GPT Dynamic Prompt）
✅ Model 作成は msdyn_TemplateId@odata.bind 形式を使用
✅ AIModelPublish (msdyn_ プレフィックスなし) で1ステップ完全アクティブ化
✅ RunConfigurationId に model_id を渡す → Run Config がその ID で作成される
✅ 更新時は Active Run Config の msdyn_customconfiguration を PATCH するだけ
❌ _msdyn_templateid_value を使う → 一部環境で拒否される
❌ _msdyn_activerunconfigurationid_value を直接 PATCH → 一部環境で拒否される
❌ statecode/statuscode を Config 作成時に指定 → 一部環境で拒否される
❌ PublishAIConfiguration を新規モデルに使う → AIModelPublish 単体で十分
❌ msdyn_AIModelPublish（msdyn_ プレフィックス付き）→ 404
❌ msdyn_Publish → 404
❌ SetState → 404
プロンプト定義
✅ prompt 配列は literal と inputVariable を交互に配置
✅ inputVariable の id は definitions.inputs の id と一致させる
✅ JSON 出力の場合は jsonSchema + jsonExamples の両方を定義
✅ modelType は有効な値を使用（gpt-41-mini, gpt-41, o3-mini）
✅ temperature は 0〜1 の float 値
botcomponent（エージェント追加）
✅ componenttype=9（トピックと同じ型番）
✅ schemaname は {botSchema}.action.{PromptNameNoSpaces} 形式
✅ YAML の kind は TaskDialog
✅ action.kind は InvokeAIBuilderModelTaskAction
✅ action.aIModelId は msdyn_aimodel の GUID（ハイフン付き小文字）
✅ inputs の propertyName は customconfiguration の inputs.id と一致
✅ shouldPromptUser: true でエージェントがユーザーに入力を求める
❌ yaml.dump() で YAML を生成 → PVA パーサーと非互換
❌ componenttype を間違える → エージェントに表示されない
ソリューション管理
✅ msdyn_aimodel の作成は solution ヘッダー付きで POST
✅ AIModelPublish 後、自動生成された Config もソリューションに含まれる
✅ AddSolutionComponent (componenttype=401) で検証・補完
❌ デフォルトソリューションに入ったままにする → 環境間移行不可
Power Automate フロー連携
✅ aibuilderpredict_customprompt で Active Model を参照（recordId パラメータ）
✅ Model が Active でないとフロー有効化時に GetPredictionSchema 検証で失敗
✅ Model → Flow の順でデプロイ（Model が Active 必須）
✅ フロー定義の dict キーに動的値を使う場合は f-string 必須
✅ 新しい Dataverse 列を追加した後は PublishAllXml でコネクタメタデータ更新
❌ Draft Model を参照するフローを有効化 → "GetPredictionSchema failed"
ファイル入力（Image or Document Input）の制限事項
公式ドキュメント: https://learn.microsoft.com/en-us/microsoft-copilot-studio/add-inputs-prompt#limitations
対応ファイル形式
| 条件 | 対応形式 |
|---|
| 標準（Code Interpreter オフ） | PNG, JPG, JPEG, PDF のみ |
| Code Interpreter オン | 上記 + Word (.doc/.docx), Excel (.xls/.xlsx), PowerPoint (.ppt/.pptx) |
サイズ・ページ数・時間制限
| 制限項目 | 値 |
|---|
| ファイルサイズ合計 | 25 MB 未満（全ファイル合計） |
| ページ数 | 50 ページ未満 |
| 処理タイムアウト | 100 秒（超過するとタイムアウトエラー） |
その他の制限
- Copilot Studio エージェントのツールとしての AI プロンプトでは画像/ドキュメント入力は未対応
- ファイル処理が必要な場合は Power Automate フロー経由で AI プロンプトを呼び出す
- 非対応ファイル形式の回避策: OneDrive for Business
ConvertFile で PDF 変換してから渡す
.env 追加パラメータ
全パラメータの定義（取得元コメント付き）は references/.env.example を参照。
実値はリポジトリルートの .env に置く（.gitignore 済み）。
# AI Builder AI Prompt 用（既存 .env に追加）
AI_PROMPT_NAME=AI Prompt Sample
AI_PROMPT_BOT_ID=https://copilotstudio.../bots/xxxxxxxx-xxxx-.../overview
# ↑ BOT_ID と異なるエージェントに追加する場合のみ指定
デプロイ・トラブルシューティング
