geekfujiwara/codeappsdevelopmentstandard/ai-builder

AI Builder で AI 処理を実装する場合、以下の方針に従う:
 
✅ AI プロンプト（カスタムプロンプト）を常に第一選択肢とする
  - 請求書処理、ドキュメント情報抽出、分類、要約 等すべて
  - プロンプトテキスト + document/image 入力で柔軟に対応
  - トレーニングデータ不要、即座にデプロイ・更新可能
  - プロンプト変更だけで出力形式・抽出項目を自由に調整
 
❌ プレビルトモデル（請求書処理モデル等）は原則使用しない
  - 従来型のプレビルトモデルやカスタムモデルはトレーニング（学習）が必要
  - AI プロンプトで同等の処理がプロンプトだけで実現できる
 
⚠ プレビルトモデルを使う例外ケース（稀）
  - 手書き文字の高精度 OCR が必須で AI プロンプトでは精度不足の場合
  - 既存のプレビルトモデルが組み込まれたワークフローを維持する必要がある場合

従来（旧パターン — ❌ 複雑で環境差異に弱い）:
  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
  → 完了!（再公開不要）

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

┌─────────────────────────┐
│  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)
└─────────────────────────┘

{
  "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": ""
}

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

✅ テンプレート 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 値

✅ 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) で検証・補完
❌ デフォルトソリューションに入ったままにする → 環境間移行不可

✅ aibuilderpredict_customprompt で Active Model を参照（recordId パラメータ）
✅ Model が Active でないとフロー有効化時に GetPredictionSchema 検証で失敗
✅ Model → Flow の順でデプロイ（Model が Active 必須）
✅ フロー定義の dict キーに動的値を使う場合は f-string 必須
✅ 新しい Dataverse 列を追加した後は PublishAllXml でコネクタメタデータ更新
❌ Draft Model を参照するフローを有効化 → "GetPredictionSchema failed"

# AI Builder AI Prompt 用（既存 .env に追加）
AI_PROMPT_NAME=AI Prompt Sample
AI_PROMPT_BOT_ID=https://copilotstudio.../bots/xxxxxxxx-xxxx-.../overview
# ↑ BOT_ID と異なるエージェントに追加する場合のみ指定