Area 3 · API 機制

score report 掉分：tool_choice + 順序編排 0%｜structured output 方法選擇 0%｜tool 分配 0% ｜讀完 → Drill 3（快檢 10 + 情境 30）

3.1 tool_choice — 四個值背死

值	行為	備註
`{"type":"auto"}`	模型自己決定要不要用工具	有給 tools 時的預設
`{"type":"any"}`	必須用某個工具（哪個它挑）	強制型
`{"type":"tool","name":"x"}`	強制用指定工具	強制型
`{"type":"none"}`	禁用工具	沒給 tools 時的預設

三個高頻事實：① disable_parallel_tool_use: true 寫在 tool_choice 物件裡面（不是 top-level 參數）——auto 時「最多一個」、any/tool 時「恰好一個」；② extended thinking 開啟時只能 auto / none，any/tool 直接報錯；③ 強制型（any/tool）副作用：模型不會在 tool_use 前輸出自然語言前言——要解釋文字就改用 auto + prompt，或在 schema 裡加 reasoning 欄位。

加碼事實：切換 tool_choice 會使 message 段的 prompt cache 失效（tool 定義與 system prompt 不受影響）——「每個 request 換 tool_choice 之後成本暴增」的題目答這個。

3.2 平行 tool use 與 tool_result 格式

assistant turn（一次回應）
  ├─ tool_use #1 (id: A)
  ├─ tool_use #2 (id: B)      ← 同回合多個 = 平行
  └─ tool_use #3 (id: C)
        ↓ 你執行（順序自選：並行/序列）
下一則 user message（一則、且 tool_result 全在文字之前）
  ├─ tool_result (id: A)
  ├─ tool_result (id: B, is_error: true ← 沒跑到也要回)
  └─ tool_result (id: C)

鐵律一：所有 tool_result 裝同一則 user message；一題一則分開回 = 教壞模型以後不 batch（官方 troubleshooting 第一名）
鐵律二：tool_result 必須在該訊息任何文字之前，否則 400 error
用 tool_use_id 對應；沒執行的呼叫回 is_error: true + 簡短說明，模型下回合會重發
鼓勵平行：system prompt 加「independent operations 就同時呼叫」；健康度指標 = 平均每則 assistant 訊息的 tool calls 數 > 1.0

3.3 依賴工具的順序編排

官方鐵律原句："if some tool calls depend on previous calls... do NOT call these tools in parallel... Never use placeholders or guess missing parameters in tool calls."

機制靠 agentic loop 天然實現：step N 的 tool_result 回到 context → 才生得出 step N+1 的正確參數（先 get_customer → 才 process_refund）
降低「依賴呼叫被誤 batch」：system prompt 加 "Only batch tool calls that are independent of each other."
要「保證叫工具 + 參數合 schema」→ tool_choice: any + tool 定義 strict: true

辨識訊號：log 裡下游工具的參數是編出來的 / placeholder（order_id: "TBD"）→ 依賴呼叫被錯誤平行化。正解永遠是「序列化依賴呼叫」，不是加 orchestration layer、不是 retry。

3.4 結構化輸出 — 方法比較表（那條 0% 就是這張表）

方法	保證強度	機制	用在
Structured Outputs（output_config + JSON schema）	確定性（constrained decoding，語法永遠合法）	解碼層約束	抽取/分類的「回應本體」
Strict tool use（`strict: true`）	保證 tool input 合 schema	同上	「動作參數」（建單、退款）
Tool use + JSON schema（經典法）	強（schema 約束 tool_use block）	逼輸出走 tool call	exam guide 語境的標準答案
Prompt-based（「請輸出 JSON」）	無保證	純指令	低關鍵度
Prefill（預填 `{`）	無正式保證	assistant 續寫	舊模型的遺留技巧

Prefill 機制：messages 最後放 assistant turn 開頭文字、模型續寫（跳前言/逼 JSON/角色維持）。限制：結尾不能是空白字元；歷史上與 extended thinking 不相容；最新一代模型已棄用（400）——官方遷移路徑 = Structured Outputs
Schema 消語法錯不消語意錯（line items 加總 ≠ total 還是要 validation）
stop_reason: "max_tokens" → 輸出截斷不合 schema → 拆小 scope 分次呼叫再合併，不是無限加 max_tokens
Schema 設計兩招（防捏造）：source 可能沒有的欄位 optional/nullable；會演化的類別 enum + "other" + detail 欄

3.5 Tool 分配 — Least Privilege

Tool 太多直接降可靠度（18 個 vs 4–5 個）——每個 agent/subagent 只給角色所需
拿到超出專長工具的 agent 容易誤用（summarizer 亂按 refund）→ scoped access 是結構性修法，prompt「請只用你該用的」不是
高頻小需求給窄 scope 專用工具（synthesis 要查單一數據 → 給一支 verify_fact），複雜需求仍走 coordinator——不要全開權限、也不要全都繞 coordinator（round-trip 爆炸）

討論題（40 分鐘 session 用）

tool_choice 四個值 + thinking 相容性，先默背一遍。然後：「必須回結構化 triage 但不限定哪個工具」用哪個值？
為什麼 tool_result 分開多則訊息回，會讓模型「以後不 batch」？從模型視角解釋。
「保證輸出合 schema」有三個不同層的機制（回應本體/工具參數/經典 tool use）——各自的參數名和適用場景？
Prefill 是什麼、為什麼被淘汰、考題問「最可靠」時它為什麼永遠不是答案？
你自己 vault 的 issue-cli 如果做成 MCP server，哪些操作該給 housekeeping agent、哪些不該？用 least privilege 講一遍。