ai-builder

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（[e-mail] 形式）
  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",  # ★ 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 構造

{
  "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}   # 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 作成は [e-mail] 形式を使用
✅ 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 と異なるエージェントに追加する場合のみ指定

デプロイ・トラブルシューティング

• 構築リファレンス — デプロイスクリプト・トラブルシューティング
• Power Automate 連携リファレンス — フロー統合パターン