ai-builder · diff
git:20260425.d670741 to git:20260521.03d13e9
135 added, 93 removed. Audit A to A.
---
name: ai-builder
- description: "AI Builder の AI プロンプト（GPT Dynamic Prompt）を Dataverse API で作成し、Copilot Studio エージェントにツール（アクション）として追加する。"
+ 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 │ ← 設定（Training + Run の 2 レコード）
+ │ msdyn_aiconfiguration │ ← 設定（AIModelPublish で自動生成）
│ (msdyn_aiconfigurations│
│ │
- │ Training (type=190690000, statuscode=6) │ ベース設定
- │ Run (type=190690001, statuscode=7) │ プロンプト定義本体
- │ msdyn_customconfiguration = JSON │
+ │ Training (type=190690000, state=2, status=6) │ Published Training
+ │ Run (type=190690001, state=2, status=7) │ Active Run Config
+ │ msdyn_customconfiguration = JSON │ ← プロンプト定義本体
└─────────────────────────┘
┌─────────────────────────┐
- │ botcomponent │ ← エージェントとの紐付け
+ │ 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": "テスト用のサンプルテキスト"
- },
- {
- "id": "document",
- "text": "document",
- "type": "document"
}
],
"formulas": [],
"data": [],
"output": {
"formats": ["json"],
"jsonSchema": {
"type": "object",
"properties": {
"summary": { "type": "string" },
- "key_points": {
- "type": "array",
- "items": { "type": "string" }
- }
+ "key_points": { "type": "array", "items": { "type": "string" } }
}
},
"jsonExamples": [
- {
- "summary": "出力例のサマリー",
- "key_points": ["ポイント1", "ポイント2"]
- }
+ { "summary": "出力例", "key_points": ["ポイント1", "ポイント2"] }
]
}
},
"modelParameters": {
"modelType": "gpt-41-mini",
- "gptParameters": {
- "temperature": 0
- }
+ "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
- - kind: AutomaticTaskInput
- propertyName: document
- name: document
- shouldPromptUser: true
-
modelDisplayName: AI Prompt Sample
+
modelDescription: AI Prompt Sample
+
action:
kind: InvokeAIBuilderModelTaskAction
aIModelId: 5f6a74ff-cd92-4f6b-a7f2-37e2be122105
outputMode: All
```
- #### botcomponent YAML フィールド
-
- | フィールド | 説明 |
- | --------------------------- | -------------------------------------------------------- |
- | `kind` | 常に `TaskDialog` |
- | `inputs[].kind` | 常に `AutomaticTaskInput` |
- | `inputs[].propertyName` | 入力変数の ID（customconfiguration の inputs.id と一致） |
- | `inputs[].name` | 入力変数の表示名 |
- | `inputs[].shouldPromptUser` | `true`: エージェントがユーザーに自動的に入力を求める |
- | `modelDisplayName` | AI プロンプトの表示名 |
- | `modelDescription` | AI プロンプトの説明 |
- | `action.kind` | 常に `InvokeAIBuilderModelTaskAction` |
- | `action.aIModelId` | `msdyn_aimodel` の GUID |
- | `outputMode` | `All`（全出力を返す） |
-
- #### schemaname 命名規則
-
- ```
- {prefix}_{botSchemaBaseName}.action.{PromptNameNoSpaces}
- ```
-
- 例: `geek_Word.action.AIPromptSample`
+ ## 構築手順
- - `prefix`: ソリューション発行者プレフィックス
- - `botSchemaBaseName`: Bot の schemaname からプレフィックスを除いた部分
- - `PromptNameNoSpaces`: プロンプト名からスペースを除去
+ 詳細な構築手順・デプロイスクリプトテンプレートは [構築リファレンス](references/build-reference.md) を参照。
+ ## Power Automate フローからの AI Builder 呼び出し
- ## 構築手順
+ AI Builder プロンプトを **Power Automate フロー内で呼び出す** パターン。
+ Copilot Studio ツールではなく、Dataverse トリガー等と組み合わせて自動実行する場合に使う。
- 詳細な構築手順・デプロイスクリプトテンプレートは [構築リファレンス](references/build-reference.md) を参照。
+ 詳細は [Power Automate 連携リファレンス](references/power-automate-integration.md) を参照。
## 絶対遵守ルール
- ### AI Model 作成
+ ### AI Model 作成（★ 最重要）
```
✅ テンプレート ID は固定値 edfdb190-3791-45d8-9a6c-8f90a37c278a（GPT Dynamic Prompt）
- ✅ Training Config → Run Config の順で作成（Run は Training を参照する）
- ✅ Run Config の statecode=2, statuscode=7 で公開済み状態にする
- ✅ Model の _msdyn_activerunconfigurationid_value に Run Config ID を設定
- ✅ Model を statecode=1 でアクティブ化
+ ✅ 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
- ✅ msdyn_aiconfiguration も solution ヘッダー付きで作成
- ✅ ソリューションコンポーネントタイプ: 401（AIConfiguration）
- ✅ AddSolutionComponent で検証・補完
+ ✅ AIModelPublish 後、自動生成された Config もソリューションに含まれる
+ ✅ AddSolutionComponent (componenttype=401) で検証・補完
❌ デフォルトソリューションに入ったままにする → 環境間移行不可
```
- ### 既存 AI プロンプトの検索・更新
-
- ```python
- # 名前で AI Model を検索
- existing = api_get(f"msdyn_aimodels?$filter=msdyn_name eq '{PROMPT_NAME}'&$select=msdyn_aimodelid,msdyn_name,_msdyn_activerunconfigurationid_value")
- if existing.get("value"):
- model = existing["value"][0]
- model_id = model["msdyn_aimodelid"]
- run_config_id = model["_msdyn_activerunconfigurationid_value"]
+ ### Power Automate フロー連携
- # Run Configuration のプロンプトを更新
- api_patch(f"msdyn_aiconfigurations({run_config_id})", {
- "msdyn_customconfiguration": json.dumps(updated_config, ensure_ascii=False)
- })
```
+ ✅ 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）の制限事項
- ```python
- # 既存 AI Model を検索 → あれば更新、なければ新規作成
- existing = api_get(f"msdyn_aimodels?$filter=msdyn_name eq '{PROMPT_NAME}'")
- if existing.get("value"):
- model_id = existing["value"][0]["msdyn_aimodelid"]
- # Run Config を更新
- ...
- else:
- # 新規作成
- model_id = api_post("msdyn_aimodels", model_body, solution=SOLUTION_NAME)
- ...
- ```
+ 公式ドキュメント: 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) を参照。
+ - [構築リファレンス](references/build-reference.md) — デプロイスクリプト・トラブルシューティング
+ - [Power Automate 連携リファレンス](references/power-automate-integration.md) — フロー統合パターン