ai-builder · git:20260521.03d13e9 · 2026-05-21 · sha256 ae8a0d7e4168dc39
ai-builder git:20260521.03d13e9A
Immutable. This exact content is served forever at /api/v1/blob/ae8a0d7e4168dc39.
---
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 の呼び出し方
```python
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", # ★ msdyn_ プレフィックスなし!
headers=headers,
json={
"TemplateId": GPT_TEMPLATE_ID, # GPT Dynamic Prompt テンプレート固定値
"ModelId": model_id, # 作成した Model の GUID
"RunConfigurationId": model_id, # ★ model_id を渡すと Run Config ID = 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}"
# → Model が Active、activeRun = model_id
```
### 重要な注意点
| 項目 | 説明 |
|------|------|
| アクション名 | `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 構造
```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）
```yaml
kind: TaskDialog
inputs:
- kind: AutomaticTaskInput
propertyName: text
name: text
shouldPromptUser: true
modelDisplayName: AI Prompt Sample
modelDescription: AI Prompt Sample
action:
kind: InvokeAIBuilderModelTaskAction
aIModelId: 5f6a74ff-cd92-4f6b-a7f2-37e2be122105
outputMode: All
```
## 構築手順
詳細な構築手順・デプロイスクリプトテンプレートは [構築リファレンス](references/build-reference.md) を参照。
## Power Automate フローからの AI Builder 呼び出し
AI Builder プロンプトを **Power Automate フロー内で呼び出す** パターン。
Copilot Studio ツールではなく、Dataverse トリガー等と組み合わせて自動実行する場合に使う。
詳細は [Power Automate 連携リファレンス](references/power-automate-integration.md) を参照。
## 絶対遵守ルール
### 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 追加パラメータ
```env
# AI Builder AI Prompt 用（既存 .env に追加）
AI_PROMPT_NAME=AI Prompt Sample
AI_PROMPT_BOT_ID=https://copilotstudio.../bots/xxxxxxxx-xxxx-.../overview
# ↑ BOT_ID と異なるエージェントに追加する場合のみ指定
```
## デプロイ・トラブルシューティング
- [構築リファレンス](references/build-reference.md) — デプロイスクリプト・トラブルシューティング
- [Power Automate 連携リファレンス](references/power-automate-integration.md) — フロー統合パターン