地基 · 一次 API 呼叫長什麼樣

1. Claude 不會執行工具 — agentic loop

初學者最大的誤解：以為給了工具，Claude 就會自己去跑。不會。Claude 只會告訴你「我想呼叫哪支、參數是什麼」，實際執行是你的程式的事。

1. 你 → API      messages（使用者問題）＋ tools（工具說明書）

2. API → 你      「我要呼叫 get_weather，參數 {city:"台北"}」
                 ← 這是 tool_use block，stop_reason: "tool_use"

3. 你的程式       自己去跑 get_weather("台北")，拿到「28度晴」
                 ← Anthropic 完全沒有參與這一步

4. 你 → API      上面全部歷史 ＋ tool_result（「28度晴」）再送一次

5. API → 你      「台北現在 28 度晴天」
                 ← stop_reason: "end_turn"，迴圈結束

這個來回叫 agentic loop（代理迴圈）。模組 2 的 2.1–2.3、模組 5 的 5.5，講的全都是這個迴圈的規則。

stop_reason 是迴圈的方向盤

你的程式靠這個欄位決定下一步做什麼，不是靠猜：

2. API 是 stateless — 每次都要全傳

第 1 個 request：tools[全部] + system + [user:"台北天氣?"]

第 2 個 request：tools[全部] + system + [user:"台北天氣?",
                                       assistant:[tool_use],
                                       user:[tool_result]]

第 3 個 request：tools[全部] + system + [上面全部 + assistant:"28度晴",
                                       user:"那高雄呢?"]

                 ↑ tools 那包從頭到尾都在，每一次都在

三個推論（後面模組會一直用到）

• 這就是 prompt caching 存在的理由——既然每次都要重送一模一樣的 tools 和 system，當然要快取。詳見 §5。
• 這就是「不要中途改 tools」是鐵律的原因——tools 排在最前面，改它等於整份快取全滅（§5 那張失效表最上面一行）。
• 這是「工具太多會降可靠度」的成本面——每支工具的完整 schema（名稱、描述、每個參數說明）每個 request 都在 context 裡。18 支工具不只讓模型選擇困難，還是每次呼叫都在燒的固定成本。對照 模組 2 §2.5。

3. Request 長什麼樣

必填只有三個：model、max_tokens、messages。其他全是選填。

POST https://api.anthropic.com/v1/messages

{
  ── 必填三兄弟 ──────────────────────────────
  "model": "claude-opus-5",
  "max_tokens": 16000,
  "messages": [ {"role":"user", "content":"台北天氣?"} ],

  ── 常用選填 ────────────────────────────────
  "system": "You are a helpful assistant.",
  "tools": [ {name, description, input_schema} ],
  "tool_choice": {"type":"auto"},              ← 模組 2 §2.1
  "thinking": {"type":"adaptive", "display":"summarized"},
  "output_config": {
      "effort": "high",
      "format": {"type":"json_schema", "schema":{…}}   ← 模組 2 §2.4
  },
  "stream": true,
  "cache_control": {"type":"ephemeral"},
  "stop_sequences": ["END"],
  "metadata": {"user_id":"…"}
}

system 是獨立參數，不是 messages 的一員

system 就是俗稱的 system prompt——角色設定、行為規則、格式要求、背景資料。它不屬於任何一輪對話，整段對話從頭到尾都掛著。

兩種寫法——要掛快取就必須用陣列形式：

// 簡單版：字串就好
"system": "You are a helpful assistant."

// 要快取就必須用 text block 陣列
"system": [
  { "type": "text",
    "text": "…很長的背景文件…",
    "cache_control": {"type":"ephemeral"} }
]

實務上 system 最值錢的用法是塞大量但穩定的背景資料（產品文件、API spec、公司規範）——因為整段對話都不變，可以整包快取。Claude Code 讀完 CLAUDE.md，就是把內容組進這個欄位，然後每輪重送（§2）。至於它為什麼排在 tools 之後、messages 之前，見 §5。

max_tokens 是輸出上限，不是總量

它管的是模型這次能吐多少，跟你送進去多少無關。給太小會被截斷（stop_reason:"max_tokens"，處理方式見 模組 2 §2.4）。實務預設：非串流 ~16000、串流 ~64000——超過約 16K 又不開串流，SDK 會撞 HTTP timeout。

認證和 beta 開關在 header，不在 body

用 SDK 時你會寫成 betas=["…"] 參數，SDK 幫你翻成 header——所以看到「某功能需要 beta header」和「SDK 的 betas 參數」講的是同一件事。

4. Response 長什麼樣

{
  "id": "msg_01XYZ…",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5",

  "content": [                        ← 永遠是陣列，元素是不同 type 的 block
    {"type":"thinking", "thinking":"…"},
    {"type":"text",     "text":"讓我查一下"},
    {"type":"tool_use",
     "id":"toolu_01ABC",              ← 記住這個 id
     "name":"get_weather",
     "input":{"city":"台北"}}
  ],

  "stop_reason": "tool_use",          ← 方向盤（§1 那張表）
  "stop_details": null,               ← 只有 refusal 時才有內容

  "usage": {
    "input_tokens": 1200,                    ← 沒快取到、全額計費
    "output_tokens": 85,
    "cache_creation_input_tokens": 0,        ← 寫入快取（~1.25x 價）
    "cache_read_input_tokens": 3400          ← 快取命中（~0.1x 價）
  }
}

usage 的三個輸入欄位

input_tokens 不是輸入總量，只是其中一塊。三個欄位加起來才是這次 prompt 的實際大小：

那個 toolu_01ABC 就是下一輪 tool_result 要用 tool_use_id 對回去的值——見 模組 2 §2.2。

5. 渲染順序與三層快取

API 內部會把 payload 拼成一段給模型看的文字，順序固定：

tools  →  system  →  messages

這個順序不是隨便排的，是按穩定程度排——最不會變的放最前面：

快取鍵不是只有 bytes

三層是巢狀的，每一層的快取鍵 ＝ 這層以前的所有內容 bytes ＋ 被歸類到這層的請求參數：

所以 tool_choice 明明是 top-level 參數、不在 messages 裡面，改它卻會打掉 messages 層——因為它被歸類為 messages 層參數（它改變的是模型生成 assistant 回應當下的行為，完全不影響 tools 和 system 怎麼被編碼）。

失效對照表（背這張）

（✅ ＝ 還活著可重用，❌ ＝ 失效要重算）

6. 這些參數已經被移除了

讀舊文章、舊教材、或問到舊版模型時會看到的寫法，在現行模型上直接 400。考題很愛拿這些當誘答：

自我檢查

不用寫字，心裡答完再展開對答案。三題都答得出來就可以去讀模組 2 了。

"usage": {
  "input_tokens":                 4200,   ← 這輪新的、沒進快取      ×1
  "cache_creation_input_tokens":  6800,   ← 這輪剛寫進快取的        ×1.25
  "cache_read_input_tokens":     73200    ← 前面幾輪命中的          ×0.1
}

實際輸入總量 = 4200 + 6800 + 73200 = 84,200 tokens