Claude Cookbooks（Anthropic 官方 notebook 食譜集）

📌 30 秒摘要

這是 Anthropic 官方維護的 Claude API 範例集：約 100 個可以直接跑的 Jupyter notebook，主題涵蓋 Managed Agents、工具呼叫、Agent SDK、RAG、評估、多模態、prompt caching、成本最佳化。日期從 2023-08 到 2026-10（MIT，★54k，查證 2026-11-02）。
量太大，這次不整包收，只挑庫裡缺的 4 篇讀完、核對官方文件，寫成工具卡或補進既有的卡。完整分類導覽放在 工具收藏 的收藏卡。

🗺 心智圖（Canvas）

Claude Cookbooks

Claude Cookbooks

🧩 怎麼組流程

工具-agent工作流的基本模式

🎯 什麼情境該想到我

當你發現「一次呼叫模型」做不好，想多呼叫幾次來換品質，卻不知道該串、該分流、該平行，還是該讓它自己改到好的時候。先從這五種固定流程挑，真的不夠再升級成自主 agent。

⚙️ 怎麼用（步驟 / 公式）

0. 先記住共同的代價

五種模式都是用更多的呼叫次數（成本、延遲）換品質。repo 範例全部只靠兩個小工具：llm_call(prompt) 送一次訊息拿回文字，extract_xml(text, tag) 用正規表示式抽出 <tag>…</tag> 之間的內容。模型輸出用 XML 標籤包起來，程式才好拆。

1. 提示鏈 Prompt Chaining：一步做一件事，接力傳下去

• 做法：準備一串 prompt，上一步的輸出當下一步的 Input:，依序呼叫。
• 範例：季報文字 → ① 抽出「數值: 指標」→ ② 換成百分比 → ③ 由大到小排序 → ④ 排成 Markdown 表格。
• 何時用：步驟固定、每步都比整件事簡單。
• 好處：每一步都能單獨檢查輸出。範例的輸出就看得到第 2 步把「$43 每位用戶獲客成本」變成 43.0，到最後表格還混在百分比欄裡。錯在哪一步一目了然。

2. 路由 Routing：先分類，再交給專門的 prompt

• 做法：第一次呼叫只做分類。prompt 列出可選的路線，要求先寫 <reasoning> 再寫 <selection>。程式抽出選擇、轉小寫，查表拿對應的專用 prompt，再呼叫第二次。
• 範例：客服工單分到 billing／technical／account／product 四組。每組 prompt 規定開頭、語氣、必含段落。
• 何時用：輸入種類差很多，一個 prompt 很難同時處理好。
• 自己補（看程式推論）：範例直接 routes[route_key]，模型若回了表外的名字就會 KeyError。正式用要加預設路線。

3. 平行化 Parallelization：同一個 prompt，同時處理多份輸入

• 做法：ThreadPoolExecutor 開 3 個 worker，每份輸入各呼叫一次，最後收齊。
• 範例：同一份「市場變化影響分析」prompt，同時套到客戶、員工、投資人、供應商四個群體。
• 何時用：子任務彼此獨立，而且事先就知道要切成哪幾份。

4. 協調者—工作者 Orchestrator-Workers：切法由模型當場決定

• 兩階段：
  1. 分析規劃：協調者模型讀任務，輸出 <analysis> 和一串 <task><type>…</type><description>…</description></task>。prompt 要求切成 2–3 個不同做法。
  2. 執行：每個工作者拿到「原始任務＋自己的 type＋description＋其他 context」，輸出 <response>。
• 和平行化的差別：子任務不是事先寫死，而是每次依輸入產生。範例是環保水壺文案，協調者自己決定寫「規格型／生活情感型／實用效益型」三版。
• 成本：N+1 次呼叫（1 個協調者＋N 個工作者）。
• 範例沒做、要自己補的：
  • 工作者是一個接一個跑的，可改用 asyncio 或執行緒池平行。
  • 工作者回空字串時，範例會塞一段錯誤訊息當結果。正式用應加重試。
  • 範例沒有彙整階段，可加一個模型把工作者的結果合起來。
  • 可以用 Opus 當協調者、Haiku 當工作者來壓成本。
• 會壞在哪：協調者切得不好（prompt 最關鍵）、工作者回空或格式錯、模型沒照 XML 格式導致解析失敗（可改用 JSON）。

5. 評估者—優化者 Evaluator-Optimizer：一個寫，一個挑，改到過關

• 做法：
  1. 生成者輸出 <thoughts> 和 <response>。
  2. 評估者只評不寫，輸出 <evaluation>（PASS／NEEDS_IMPROVEMENT／FAIL）和 <feedback>。只有完全沒建議時才能給 PASS。
  3. 不是 PASS，就把「之前所有版本＋這次回饋」塞回生成者的 context，再生一版。
• 範例：實作 O(1) 的 push／pop／getMin 堆疊。第一版演算法正確，評估者仍要求改：空堆疊要丟例外、補型別標註和 docstring。
• 適用的兩個訊號：① 給了回饋，產出確實會變好；② 模型自己就能給出有意義的回饋。前提是評分標準清楚。
• 自己補（看程式推論）：範例的迴圈是 while True，沒有次數上限。評估者標準太嚴（「沒有任何建議才 PASS」）時可能停不下來。一定要加最大輪數。

6. 怎麼選

你的狀況	選
步驟固定、可以拆成依序的小步	提示鏈
輸入分好幾類，各類處理方式不同	路由
子任務獨立，切法事先知道	平行化
子任務獨立，但切法要看輸入才知道	協調者—工作者
有明確評分標準，改一輪會更好	評估者—優化者

模式可以疊：路由之後接提示鏈，協調者的工作者再各自跑評估迴圈。

7. 什麼時候才升級成自主 agent

repo 對「何時升級」沒有直接寫判準。以下是推論：上面五種的步驟數和分支都由你的程式碼決定；當「要做幾步、下一步做什麼」得看中途查到的結果才知道，固定流程寫不出來時，才換成讓模型自己決定下一步的 agent。

升級後，repo 的研究型 agent prompt（prompts/research_lead_agent.md、research_subagent.md）示範了要另外加的預算規則：

• 先判斷題型再決定派幾個子 agent：直接題 1 個；一般 2–3 個；中等 3–5 個；高複雜 5–10 個，上限 20 個。「更多子 agent＝更多開銷」，寧可少而能幹。
• 子 agent 自訂工具呼叫預算：簡單題 5 次以下、中等約 5 次、難題約 10 次、非常難最多 15 次；硬上限 20 次呼叫、約 100 個來源，超過就被終止。
• 報酬遞減就停：已經能給夠好的答案，就不再派新的子 agent，直接寫報告。
• 最終報告由主 agent 自己寫，不外包給子 agent。

🧪 我實際套用的紀錄

• 2026-11-02：（待填）

⚠️ 注意 / 什麼時候不適用

• repo 明說這些是示範核心概念的範例，不是正式產品程式碼：沒有重試、逾時、輪數上限。
• 單一輸出、一次呼叫就夠好的任務，不要硬套。協調者—工作者在「簡單任務」「延遲很敏感」「子任務永遠一樣」時都不建議用。
• 用 XML 標籤解析時，模型漏標籤 extract_xml 會回空字串，不會報錯。下游要檢查空值。
• 多個模型分頭做會有上下文分裂、錯誤放大的問題，見 多 Agent 編排與 Agent Drift。

🔗 相關工具

• 多 Agent 編排與 Agent Drift：多 agent 拓撲、何時有用、何時垮掉、偏移診斷
• ReAct 與 Agent Loop：升級成自主 agent 後的迴圈怎麼寫、怎麼停
• 工具-AI-Agent設計：agent 的規劃、工具、記憶三要素
• 工具-agent的測試金字塔：換模式後怎麼確認沒變差
• 工具-讓模型寫程式一次呼叫多個工具：工具呼叫很多時，把迴圈交給模型寫的程式碼

🔧 怎麼省 token

工具-讓模型寫程式一次呼叫多個工具

🎯 什麼情境該想到我

當 agent 要對很多筆資料重複呼叫同一個工具，每次回傳又是一大包，而真正需要的只是篩選、加總後的幾行結論。這時讓模型寫一段程式，在沙盒裡自己跑迴圈呼叫工具、自己算，只把結果交回來。

⚙️ 怎麼用（步驟 / 公式）

1. 機制：工具結果改由程式碼接收

• 傳統工具呼叫：模型每要一次工具，就停下來（stop_reason == "tool_use"）。你執行工具，把 tool_result 放回對話，再呼叫模型。每一筆原始結果都進模型的上下文。
• PTC：模型先用 code execution 工具寫一段 Python。程式裡把你的工具當成 async 函式呼叫，例如：

  team = json.loads(await get_team_members({'department': 'engineering'}))
  results = await asyncio.gather(*[
      get_expenses({'employee_id': m['id'], 'quarter': 'Q3'}) for m in team
  ])

  程式跑到工具呼叫時，API 回應裡會出現 tool_use 區塊，上面的 caller 標明是程式發起的。你照樣執行工具、照樣用 tool_result 回傳，但這份結果只交給沙盒裡的程式，模型看不到。程式篩選、加總完，只 print 出結論，模型讀到的只有這段輸出。
• notebook 原文：「只有 direct 呼叫會被模型『看到』；code_execution_20250825 類型只有 code execution 容器看得到。」

2. 設定（照 notebook 原文）

1. 每個要開放給程式呼叫的工具，加上 allowed_callers 欄位：

   tool["allowed_callers"] = ["code_execution_20250825"]

   • 沒有 allowed_callers 的工具，預設只能由模型直接呼叫。
   • 兩種都允許就寫 ["direct", "code_execution_20250825"]。
   • 只開放可以安全重複執行的工具。
2. 在 tools 陣列加上 code execution 工具：

   {"type": "code_execution_20250825", "name": "code_execution"}

3. 用 beta 版 messages API：client.beta.messages.create(..., betas=["advanced-tool-use-2025-11-20"])。
4. 有狀態的流程要帶容器 ID：從 response.container.id 取得，下一次請求用 extra_body={"container": container_id} 傳回去。notebook 說單輪流程不需要。
5. 處理工具呼叫時讀 block.caller["type"]："direct" 是模型直接叫的，"code_execution_20250825" 是程式叫的。兩種都要回 tool_result。

⚠️ 官方文件已改版（查證 2026-11-02，Claude 官方文件 programmatic-tool-calling、code-execution-tool 頁）：

• PTC 現在需要 code_execution_20260120 或更新版（另有 code_execution_20260521）。code_execution_20250825 只支援 Bash 與檔案操作，不支援 PTC。
• allowed_callers 改寫 ["code_execution_20260120"]。20260120 與 20260521 可互通，回應裡的 caller 一律標 code_execution_20260120。
• 三個 code execution 版本都不需要 anthropic-beta header，官方範例直接用 client.messages.create，容器用 container= 參數傳。舊 beta header 仍可用。
• Claude Haiku 4.5 接受新版工具型別，但不支援 PTC。可從 Models API 的 capabilities.code_execution.supported 確認模型是否支援。
• notebook 工具定義裡的 input_examples（給模型看的輸入範例），官方仍標為 beta。

3. 工具描述要寫清楚回傳格式

notebook 每個工具的 description 都多一段 RETURN FORMAT，例如「回傳 JSON 字串，是陣列不是包在物件裡，用 json.loads() 解析」。推論：程式碼看不到結果長相就得先寫好解析邏輯，回傳格式講不清楚，程式會解析錯。

4. 划算多少（notebook 單次實驗結果）

任務：找出 8 位工程師中誰超過 Q3 差旅預算（標準 $5,000，超過的人再查有沒有自訂預算）。每人有 20–50 筆帶大量欄位的費用紀錄。

指標	傳統	PTC
API 呼叫	4	4
總 token	110,473	15,919
耗時	35.38 秒	34.88 秒
減少	—	token −85.6%、時間 −1.4%

• token 省在哪：傳統做法第 3 輪光輸入就 51,744 token，全是原始費用紀錄。PTC 各輪輸入約 4–6 千。
• 推論：時間幾乎沒省，可能因為 mock API 的模擬延遲 DELAY_MULTIPLIER = 0，工具本身不花時間，往返省下的延遲顯不出來。
• 兩邊算出的數字不一樣：傳統做法讓模型心算，Alice 的差旅合計是 $6,753.62；PTC用程式加總是$9,177.88。同一個 kernel 裡 mock 資料相同，推論是模型心算漏了項目。這正是 notebook 說的第三個好處：算術交給程式，結果精確。

5. 什麼時候用

notebook 列的五個條件：

• 資料量大、欄位多，需要篩選、解析、彙總。
• 有前後相依：下一個工具要看前一個結果才決定要不要叫。
• 同一種呼叫要對很多個對象跑迴圈。
• 用運算邏輯可以縮減要進上下文的內容。
• 工具可以安全地重複執行，不需要人盯著。

特別適合你改不動的第三方 API：回傳太肥也沒辦法改，就讓程式先過濾。

🧪 我實際套用的紀錄

• 2026-11-02：（待填）

⚠️ 注意 / 什麼時候不適用

• 呼叫次數不一定變少：notebook 文字說 PTC 在這例子需要更多次 API 呼叫，但表格是 4 比 4，另一格又印出 3。省的是 token，不是往返次數。
• 會被重複呼叫、會改資料的工具要慎開：程式可以在迴圈裡連打很多次，模型和人都不會逐筆看到。
• 以下限制出自官方文件（查證 2026-11-02），notebook 沒提：
  • 回覆等待中的程式呼叫時，那則 user 訊息只能有 tool_result，不能夾文字；內容只能是字串或 text，不能是圖片、文件。
  • 程式在等工具結果時約 4 分鐘逾時，程式內會拋 TimeoutError。容器閒置約 5 分鐘會被收；等待中的請求一定要帶容器 ID，否則 API 拒絕。
  • code_execution_20260521 每個 Python cell 有 90 秒上限。
  • 不能用：strict: true 的工具、用 tool_choice 強制程式呼叫某工具、disable_parallel_tool_use: true。MCP connector 提供的工具、computer use／browser use 工具集不能被程式呼叫。
  • 計費：程式呼叫的工具結果不算輸入／輸出 token，只算最後的程式執行結果和模型回覆。
• 工具只回一小段結果、或只呼叫一兩次時，多一層程式反而增加成本與複雜度（推論）。

🔗 相關工具

• 工具集設計：工具回傳要精簡、截斷要明示——改得動工具時先從這裡下手
• Function Calling 與結構化輸出：傳統工具呼叫的基本流程
• ReAct 與 Agent Loop：上下文隨輪數超線性成長，PTC 是其中一種解法
• 工具-agent工作流的基本模式：固定流程的模式，和讓模型寫程式編排是兩條路

前綴快取 Prompt Caching

對應原題（Common ‧ Inference, Serving and GPU Performance）

• Explain prefix caching / prompt caching. When should you use it, and what invalidates a cached prefix?
  — Asked at: Moonshot AI, Character.AI

🎯 什麼情境該想到我

當你「有一段很長的 system prompt / few-shot / 工具定義每次請求都要重送」的時候。這是唯一一個能同時砍掉延遲和成本、而且完全不影響輸出品質的優化——而且多數人設定錯了還不知道。

⚙️ 怎麼用（機制）

它在快取什麼

不是快取「答案」，是快取 prefill 算出來的 KV cache。

請求 1: [system prompt 2000 tok][few-shot 3000 tok][問題 A]
            └──── prefill 一次，KV 存起來 ────┘
請求 2: [system prompt 2000 tok][few-shot 3000 tok][問題 B]
            └──── 直接載入，不用重算 ────┘  只 prefill 問題 B

同樣的輸入必然算出同樣的 K、V，所以重用是數學上無損的——輸出品質完全不變。

★ 為什麼「只能是前綴」

因為 causal attention：位置 $i$ 的 K、V 只依賴 $0\dots i$ 的內容。

所以只要有任何一個 token 改變，它之後的所有 KV 全部作廢。 前面不變、後面變 → 可以重用前面。前面變了 → 全丟。

這一條推論出後面所有的設計原則。

★ 設計原則：穩定的放前面，變動的放後面

這是唯一真正重要的實務規則：

✅ 正確的排列
┌────────────┬──────────┬─────────┬──────────┬──────────┬────────┐
│ 工具定義    │ system   │ few-shot│ 檢索文件  │ 對話歷史  │ 當前問題│
└────────────┴──────────┴─────────┴──────────┴──────────┴────────┘
  ←─────────── 越左邊越穩定 ───────────────────────────────→ 每次都變

❌ 常見錯誤
┌──────────────────────┬────────────┬──────────┐
│ "現在時間 2026-09-20  │ 工具定義    │ system   │   ← 整個快取永遠不命中
│  14:23:07，使用者 ID…"│            │          │
└──────────────────────┴────────────┴──────────┘

把時間戳、request ID、使用者 ID 放在 prompt 最前面，是一個能讓快取命中率歸零的單行 bug。
需要它們就放最後面。

Anthropic API 的實作（2026-09-20 查證自官方文件）

兩種用法：

方式	做法
自動快取	在 request body 頂層加 cache_control，系統自動把斷點放在最後一個可快取區塊，並隨對話成長自動前移
顯式斷點	在個別 content block 上放 cache_control，精確控制快取邊界

快取的範圍：tools → system → messages（照這個順序），一路到標有 cache_control 的那個 block 為止。

價格結構（相對 base input token 價）：

項目	倍率
5 分鐘 TTL 寫入	1.25×
1 小時 TTL 寫入	2×
快取讀取	0.1×（Opus 5.5／Sonnet 5.5 為 0.05×；Fable 5.1／Mythos 5.1 為 0.025×；查證 2026-11-02）

→ 寫入貴一點點，讀取便宜 10 倍以上。 5 分鐘 TTL：寫入 1 次之後讀 1 次就回本；1 小時 TTL 要讀 2 次（官方文件，查證 2026-11-02）。

最低可快取長度（不到就靜默不快取，不會報錯）：

模型	最低 token
Fable 5.1 / Mythos 5.1 / Opus 5.5 / Opus 5 / Sonnet 5.5 / Fable 5 / Mythos 5 / Haiku 5.5	512
Opus 4.8 / Sonnet 5 / Sonnet 4.6 / Sonnet 4.5	1,024
Mythos Preview / Opus 4.7	2,048
Opus 4.6 / Opus 4.5 / Haiku 4.5	4,096

（最低長度表於 2026-11-02 依官方文件更新。）

驗證有沒有命中：看 response 的 cache_creation_input_tokens 與 cache_read_input_tokens。兩個都是 0 就代表根本沒快取到（多半是沒達到最低長度）。差一點點就達標時，把快取內容補長到門檻反而更省錢。

其他機制：

• 20 個 block 的 lookback window —— 斷點只在你標記處寫入，不會自動往回找穩定內容
• 多個斷點不額外收費 —— 只按實際快取與讀取的量計價，所以可以大方地標多個邊界，讓不同變動頻率的區段各自快取

★ 一個必踩的坑（官方文件明確點名）

你的 prompt 是：block 1–5 是大段靜態內容，block 6 是「時間戳 + 使用者訊息」。你把 cache_control 放在 block 6。

結果：永遠不命中。 因為快取寫入只發生在斷點處，而斷點的 hash 包含了每次都在變的 block 6。lookback 不會回頭幫你快取斷點之前的穩定內容——它只找「先前的請求已經寫入的條目」。

正解：把 cache_control 放在 block 5（最後一個跨請求不變的 block）。

⚠️ 自動快取也會踩同一個坑——它把斷點放在「最後一個可快取區塊」，在這種結構下正好是每次都變的那個。後綴會變（時間戳、per-request context、當前訊息）時，一定要用顯式斷點放在靜態前綴的結尾。

使用者還在打字時，先把快取暖好（Speculative Prompt Caching）

想解決的問題：快取第一次寫入時，整段前綴的 prefill 會落在使用者按下送出之後。前綴很大時，第一個字要等很久。
做法：使用者一打開輸入框（或開始打字），就用「同一段前綴」在背景先發一個請求，讓快取寫進去；等他送出時，正式請求直接讀快取。

實作重點（Claude Cookbooks 的 speculative_prompt_caching notebook）：

1. 大段內容（範例是 SQLite 的 btree.h＋btree.c）放進第一個 content block，並在這個 block 上加 cache_control: {"type": "ephemeral"}。
2. 用 asyncio.create_task 在背景送暖身請求：messages=[這個 block]、max_tokens=1。只要讓它跑完 prefill，不需要它的回答。
3. 使用者送出後，深拷貝同一個 block，在後面附加一個問題 block，再送正式請求。前綴逐字相同，才會命中。
4. 送正式請求前先 await 暖身任務。官方文件說明：快取條目要等第一個回應開始後才能用；同時並發的請求不會互相命中（查證 2026-11-02）。

notebook 的實驗（Sonnet 5.5，約 15.2 萬 token 的前綴，模擬打字 3 秒）：

	首字延遲 TTFT	總時間	快取
一般做法	20.87 秒	28.32 秒	寫入 151,629
預先暖快取	1.94 秒	8.40 秒	讀取 151,629

官方的新做法（查證 2026-11-02）：暖身請求可以設 max_tokens: 0。API 寫完快取就立刻返回，content 是空陣列，stop_reason 是 "max_tokens"。但有幾個限制：

• 這個設定不能搭配 stream、extended thinking、structured outputs、部分 tool_choice，也不能用在 Message Batches 裡。
• 暖身請求的 thinking 設定和 effort 必須跟正式請求一致，否則寫進去的條目沒人會命中。

什麼時候不值得做：

• 打字時間比 prefill 時間短。notebook 的 TTFT 是在 await 暖身任務「之後」才開始計時。範例中 prefill 大約要 20 秒，打字只有 3 秒，所以使用者實際從送出到看到第一個字，大約還要等 17＋1.9 秒。推論：真正省下的時間 ≈ min(打字時間, prefill 時間)。
• 使用者常常沒送出就離開。這時寫入費等於白付：以 Sonnet 5.5（input $2/MTok）計，約15.2萬\times 2\times 1.25÷10^6\approx \ast \ast$0.38**（查證 2026-11-02）。如果使用者有送出，暖身本來就要寫入，多出來的只是一次讀取：15.2 萬 × $0.10/MTok\approx$0.015。
• 前綴每次都不同，或比最小可快取長度還短：暖了也不會命中。
• 前綴開頭放時間戳：notebook 為了讓每次執行都不共用快取，刻意把時間戳放在最前面。正式產品不要照抄。
• 從暖身到送出之間不能超過 TTL（預設 5 分鐘）。超過就要重新暖身，或改用 1 小時 TTL。

★ 什麼會讓快取失效（面試題的後半，2026-09-20 查證）

一、內容本身

• 前綴的任何一個 token 不同——包含空白、標點、JSON 欄位順序
• 在前面插入內容 → 後面所有 token 的位置都偏移 → RoPE 角度全變 → KV 全部作廢（這是為什麼「在中間插一段」比「在後面加一段」貴得多）

二、請求參數（Anthropic 官方的失效表）

變動	tools 快取	system 快取	messages 快取
修改工具定義（名稱／描述／參數）	✘	✘	✘ —— 整個快取失效
開關 web search	✓	✘	✘（會改動 system prompt）
開關 citations	✓	✘	✘
切換 speed: "fast"	✓	✘	✘
改 tool_choice	✓	✓	✘
增刪任何位置的圖片	✓	✓	✘
改 thinking 參數（模式 / budget）	視模型	視模型	✘
改 output_config.effort	視模型	視模型	✘

（✓ = 仍有效、✘ = 失效）

兩個反直覺的重點：

1. 改工具定義會把整個快取打掉——連 system 和 messages 都一起。工具 schema 要穩定，別動態生成。
2. thinking / effort 的設定是被渲染進 prompt 的，所以改它一定讓 message 快取失效。

不影響快取的：temperature、top_p、max_tokens 等取樣參數——因為 KV 與取樣無關。

三、時間與容量

• TTL 到期（Anthropic 預設 5 分鐘，可選 1 小時）
• 自架時的 LRU 驅逐——顯存不夠就丟

四、環境

• 模型版本、量化方式、推論框架版本、tensor parallel 配置改變 → 全部作廢

什麼場景該用

場景	效益
長 system prompt / 大量 few-shot	⭐⭐⭐ 典型用例
Agent loop	⭐⭐⭐ 每一步都重放整段歷史+工具定義，這是最賺的場景
多輪對話	⭐⭐⭐ 歷史是天然的成長前綴（自動快取就是為此設計）
同一份文件問很多問題	⭐⭐⭐ 文件當前綴
批次處理同模板不同資料	⭐⭐ 模板在前、資料在後
每次 prompt 都完全不同	❌ 純虧（付了寫入費卻沒人讀）
prompt 短於最低門檻	❌ 靜默失效

⚠️ 注意 / 什麼時候不適用

• 上面的價格、TTL、最低長度會變。本頁數字查證於 2026-09-20，以 https://platform.claude.com/docs/en/docs/build-with-claude/prompt-caching 為準。
• 不同廠商機制不同：OpenAI 是自動、無需標記；Google 需要顯式建立 context cache。跨廠商時不能假設行為一致。
• 失敗是靜默的。沒達到最低長度不會報錯，只會安靜地照全價算。一定要監控 cache_read_input_tokens 的比例。
• 快取不減少 context window 佔用。省的是計算與錢，不是 token 額度。
• thinking block 不能直接用 cache_control 快取，但出現在先前 assistant 回合時可以隨其他內容一起被快取；從快取讀出時仍計入 input token。
• 自架（vLLM）的前綴快取要顯式開啟（--enable-prefix-caching），且前綴不重複的流量會純虧 hash 開銷。
• 安全考量：多租戶環境下要確保不同使用者的快取不會互相命中——別把使用者資料放進共用前綴。

🧪 我實際套用的紀錄

• 2026-09-20：從面試題庫展開，Anthropic 側細節已查證官方文件。待辦：檢查自己的 agent 是否把變動內容放在了前面。

🔗 相關

• PagedAttention 與 vLLM —— 自架時的底層機制（block 共享）
• KV Cache —— 被快取的東西
• Prefill 與 Decode —— 省掉的是 prefill，直接改善 TTFT
• 服務棧選型與降本 —— 降本槓桿排序中最優先的一項
• ReAct 與 Agent Loop —— 受益最大的場景
• 工具-agent成本最佳化清單 —— 快取在整份降本清單裡排第幾、和其他手法怎麼疊

💰 怎麼省錢

工具-agent成本最佳化清單

🎯 什麼情境該想到我

當你的 agent 已經能用，但量一放大帳單就撐不住；你想省錢，又不想靠「換小模型」把品質換掉的時候。

⚙️ 怎麼用（步驟 / 公式）

0. 先量，再省：兩個數字一起看

• 先在強模型上做出能用的版本，再談省錢。做不出「一個」能用的 agent，就做不出便宜的。
• 建一個小 eval：幾個有標準答案的代表任務就夠。notebook 用 10 筆保險理賠、人工標好的判決。
• 每個設定都記兩個數：通過率、每任務成本（把每次回應的 usage 加總後換算成美元）。
• 看「每任務」不看「每 token」：單價高的模型如果少走幾輪，整體可能更便宜。
• 品質門檻當限制，成本當要最小化的目標。 notebook 的門檻是 10/10。

成本換算（notebook 的 usage_cost）：

成本 = 一般輸入×P_in + 5分鐘快取寫入×1.25P_in + 1小時快取寫入×2P_in
     + 快取讀取×0.1P_in + 輸出×P_out          （Batch 再 ×0.5）

倍率對官方價目查證 2026-11-02：寫入 1.25×／2×、讀取 0.1× 正確。但 Opus 5.5、Sonnet 5.5 的讀取是 0.05×，Fable 5.1、Mythos 5.1 是 0.025×。換新模型時要改這個常數。

1. Pareto 前緣：怎麼挑出「值得的」設定

• 每個設定跑多次，取平均通過率和平均每任務成本。
• 依成本由低到高排序，只保留「比所有更便宜的設定都更準」的點，這些點連成前緣。
• 不在前緣上的設定就是「比較貴，卻沒有比較準」，直接淘汰。
• 判斷一個新手法有沒有用，只看一件事：它有沒有把前緣往左推（同樣準確，但更便宜）。
• 同一設定兩次結果可能不同（Sonnet low 一次 9/10、一次 8/10）。上線前，notebook 建議約 50 個案例、每設定至少 5 次。

2. 清單（建議照這個順序檢查）

以下數字都是 notebook 的單次實驗結果：模型 Opus 5、Sonnet 5、Haiku 4.5，任務是假想保險公司的理賠 agent，固定前綴約 13K token（system prompt 內嵌一份約 11–12K token 的核保手冊，加上 12 個工具）。你的數字一定不同。

#	手法	做法	notebook 單獨示範省多少
1	提示快取	頂層 cache_control 自動快取；不同對話共用前綴時，在 system 尾端加顯式斷點；兩次呼叫間隔超過 5 分鐘就用 1 小時 TTL	2 次追問 −32%；時間戳移出 system −44%；穩定內容放前面 −54%
2	輸入瘦身	少用的參考資料改成工具按需讀取；刪掉 system 裡重述工具清單的段落；工具多時用 tool search（defer_loading）；圖片先縮圖；大表格用 Files API ＋ code execution	前綴 13,462 → 2,517 → 2,125 → 1,696 token；圖片 4,088 → 928 token；CSV 135K token 直接貼入 → 改跑程式 −79%
3	agent 迴圈控制	伺服器端的 context editing、compaction；用戶端在自然邊界一次修剪（jagged compaction）；自成一塊的子任務丟給 subagent	3 筆理賠排隊、中間塞一份 135K 的帳本：−12%／−16%／−29%／−78%
4	輸出控制	在 prompt 寫死輸出格式並附範例；max_tokens 只當防暴走的上限；無法處理時讓模型輸出哨兵字串，並設成 stop sequence	備忘錄 4,096 → 61 output token，−63%；壞輸入 −56%
5	Batch API	不急的工作送非同步佇列，24 小時內完成	同樣 token，−50%
6	effort 與模型	先降 effort，還能過門檻就降一級模型，effort 重設為 high 再往下掃	見下表

為什麼「換模型」排最後：前面幾項只改變「同樣的 token 付多少錢」或「送了哪些 token」，模型能力不變；換模型是直接拿能力換錢。

3. 掃模型與 effort（notebook 的 10 筆 eval，各跑 2 次）

設定	通過	每任務成本
Opus high，無快取（基準）	10/10	$0.2906
Opus high＋自動快取	10/10 ×2	~$0.150（−48%）
Opus low＋快取	10/10 ×2	~$0.121
Sonnet medium＋快取	10/10 ×2	~$0.050
Sonnet low＋快取	9/10、8/10	~$0.050
Haiku＋快取	7/10、4/10	~$0.019

再把各手法逐一疊到 Sonnet medium 上：

疊加	通過	每任務成本	結果
＋system 顯式斷點	10/10 ×2	~$0.0225	唯一推動前緣的手法：比基準便宜約 13 倍
＋手冊改成工具讀取	9/10 ×2	~$0.021	省錢，但掉準確
＋tool search	8/10、9/10	~$0.054	反而更貴
＋code execution	10/10 ×2	~$0.0585	反而更貴
＋context editing／compaction	10/10；10/10、9/10	~$0.050	沒效果（觸發門檻沒被碰到）
Haiku 子代理收集事實＋Sonnet 判決	9/10 ×2	~$0.019	最便宜，但差一題
改成一次性 Batch	9/10 ×2	$0.006／$0.019	差一題，而且批次內快取命中不穩

顯式斷點為什麼有效：自動快取只在同一段對話內攤提前綴。每筆新理賠是新對話，第一輪都要重寫一次手冊；在 system 後面加一個斷點，之後每筆理賠都能直接讀快取。

快取何時回本可以自己算：同一前綴 P 被用 n 次，不快取付 nP，快取付 1.25P＋(n−1)×0.1P。n=2 時是 1.35P 對 2P，省 32.5%，與 notebook 實測的 32% 吻合。

🧪 我實際套用的紀錄

• 2026-11-02：（待填）

⚠️ 注意 / 什麼時候不適用

• 手冊改成工具讀取：模型只看得到它想到要查的段落，邊界案例會漏規則。整份文件大多數呼叫都會讀到時，留在快取裡反而便宜。
• tool search：工具 schema 要到約 10K token 以上才划算。notebook 只有幾百 token，搜尋這一步純粹是額外開銷。
• code execution：任務裡沒有數值運算就別加。另外它會額外收沙箱時間費。
• context editing、compaction、修剪：只對會長到很長的迴圈有用。每次編輯都會讓「編輯點之後」的快取失效，所以要讓它少發生。compaction 的預設觸發點是 150K、下限 50K。在有 preserved thinking 檢查的模型上，用戶端改寫早期回合，會讓後面的 thinking block 失效。
• subagent／拆解：子代理從零開始建前綴，不能共用父代理的快取。把手冊壓縮成規則卡會丟掉例外條款，notebook 就因此誤拒一筆該核准的理賠（被拒駕駛其實是同住的兒子）。
• advisor 工具（便宜模型當主力、Opus 待命）：要有便宜又明確的訊號（金額門檻、風險分數區間）決定何時諮詢才有用。叫弱模型自己判斷「這題難不難」，需要的正是它缺的判斷力。
• Batch：有人在等回應，或下一步要看上一步結果才知道要抓什麼，就不能攤平成單次請求。24 小時是「到期時間」，不是服務保證。
• effort 是渲染進 prompt 的：對話中途改 effort、換模型，快取都會失效。
• 和 服務棧選型與降本 的排序不同：那張卡（自架服務的角度）把模型路由排第 2，視為最大的一筆。這份 notebook 也證實換模型的跌幅最大（Opus→Sonnet 約 −67%），但仍排最後，因為它是唯一直接犧牲能力的手段。推論：兩者不矛盾。先拿走不傷品質的錢，再用 eval 決定能力能讓多少。
• 所有價格都是快照（查證 2026-11-02），新模型上市後，倍率和最小可快取長度都會變。

🔗 相關工具

• 工具-AI改動的AB對照評測 —— 為什麼一定要多跑幾次：雜訊底線要先量
• 工具-AI系統評估 —— 怎麼建這份 eval（本卡假設 eval 已經有了）
• 前綴快取 Prompt Caching —— 第 1 項的機制、失效條件與最小長度
• 服務棧選型與降本 —— 自架服務的降本槓桿，與本卡的 API 角度互補
• 工具-長對話的Token預算分配 —— 迴圈控制的另一面：上下文要怎麼分配

📚 其他 95 篇

工具收藏

收藏自己打開來用的外部工具：網站、本機應用、素材庫、圖鑑。就算背後有 AI，只要不是裝進 agent 裡的，都放這裡。
裝進 agent 裡用的 skill／plugin／MCP 收在 AI 技能收藏。

每張卡記「做什麼、怎麼用、要注意什麼、我試了沒」。

圖例　型態：網站 本機應用　狀態：⬜ 待試・✅ 已在用
（★ 為查看當時概數，非即時。）

📇 快速索引

🎨 設計與視覺素材（2）

名稱	型態	平台	一句話	來源	狀態
Motion Library 動態收藏	網站	瀏覽器	327 種網頁動效圖鑑，可交叉篩選、每格附可複製的 AI 提示詞	網站↗	⬜
Mesh Avatar Studio	本機應用	Claude Code・Codex 驅動	一張插畫 → 會眨眼說話轉頭的 2D 網格虛擬形象，agent 綁骨架、人在編輯器微調，可接 OBS 直播	repo↗	⬜

🤖 AI 開發參考（1）

名稱	型態	平台	一句話	來源	狀態
Claude Cookbooks	網站	GitHub（Jupyter notebook）	Anthropic 官方的 Claude API 食譜集：約 100 個可跑的 notebook，從工具呼叫、RAG、評估到 agent 模式	repo↗	⬜

---

🎨 設計與視覺素材

Motion Library 動態收藏

網站 · 網頁（Hannah，UI/UX Designer 整理） · 327 種（2026-10-29） · ⬜ 待試

做什麼：一本網頁動態效果的圖鑑。想在頁面上加動效、卻說不出要什麼樣子時，先在這裡挑，再把描述丟給 agent 照做。

• 三軸交叉篩選：「元件」（文字 105、按鈕、卡片、背景、游標…）×「時機」（進場、退場、切換、循環待機、懸停點擊、捲動觸發、拖曳）×「情境」（標題 Hero、強調重點、數字資訊、轉場…），例如「按鈕 × 懸停」。另可依技術篩：CSS 194、GSAP 119、Canvas 14。
• 每格都有可試玩的預覽，互動類可以直接用滑鼠移動、捲動、拖曳。
• 「複製 AI 提示詞」複製的是外觀與節奏的描述，不是程式碼。例如閃電砸落：「先閃兩下強光並出現一道閃電線，文字從 2 倍大瞬間砸下縮回原尺寸，落地時輕微震動……整段約 2.4 秒」，最後一律加上「配色請依照網站既有的主題色」。

怎麼用：篩到想要的效果 → 複製提示詞 → 貼給 Claude Code 等 agent，並說明要套在哪個元件、用 CSS 還是 GSAP。描述裡的秒數、縮放倍率就是驗收時對照的規格。

⚠️ 注意

• 預覽是作者重製的示意，名稱與描述來自 Threads 上其他人的整理。網站自述「僅供個人參考學習」，不要整段照抄到商用作品。
• 提示詞只描述外觀，沒有效能與無障礙要求。實作時要自己補（我的建議）：尊重 prefers-reduced-motion、只動 transform／opacity，避免觸發重排。
• GSAP 類的效果是用 GSAP 3.13 示範的。
• 我還沒實際拿提示詞讓 agent 做過，產出品質未驗證。

---

Mesh Avatar Studio

本機應用 · Claude Code・Codex · MIT（範例角色 Miko 另有授權） · ★1.6k（2026-10-30） · ⬜ 待試

做什麼：給一張插畫，做出會眨眼、說話、轉頭、呼吸、頭髮會飄的 2D 網格虛擬形象（mesh avatar），可以用自己的臉和聲音即時驅動，接進 OBS 直播。分工是：coding agent 負責綁骨架、切圖層、自我檢查，人在本機編輯器拖點微調。它不是 skill，而是一個 repo：你在 repo 裡開 Claude Code 或 Codex，agent 照 docs/agent-guide.md 一步步做。

核心（agent guide 的設計值得看）

• 先驗模型的視力，不合格就停：開工前先跑 vision-check.py，產生一張帶編號標記的圖，讓模型讀座標、打分數。分數不及格，就告訴使用者「這個模型讀到的座標很可能偏掉，後面大多要手修」。指南也要求 agent 先報自己是哪個模型，不在推薦清單上就先問要不要繼續。
• 座標一律在放大的網格上讀：用 grid.py 畫格線，再逐區放大。「直接看整張圖估座標」被列為不可接受。
• 用固定姿勢的渲染圖自我審查：render-poses 會輸出閉眼、張嘴、左右轉 ±30°、抬頭低頭、各種表情、頭髮擺動的截圖與接觸表，逐張檢查，例如閉眼不能露出虹膜、轉頭不能撕裂網格。沒看圖就回報成功也被列為不可接受。
• 素材不出本機：插畫只放在 projects/，不 commit、不上傳。唯一例外是第 6 步，要畫閉眼、嘴型、表情的差分圖時，經使用者同意才把圖和遮罩送去產圖。

裝與用

# 需要 Node.js 22.17+ 與 Git
npx create-mesh-avatar-studio
cd mesh-avatar-studio
npm run dev          # 開編輯器，先看內附範例

• 讓 agent 做自己的角色：在 repo 裡對 agent 說「Create an avatar from this image following docs/agent-guide.md: /path/to/your-image.png」。正面、露出頭肩、透明背景的 PNG 效果最好。
• Codex 一鍵版：npm run create -- /path/to/image.png。通常要花幾十分鐘。--random 可以讓 Codex 先畫一個新角色再做。
• 完整流程要 Python 3.10＋uv 與 Playwright Chromium，npm run doctor 會列出缺什麼。
• 輸出：可匯出單一 .mavatar 檔分享。Live 頁可以接攝影機與麥克風，複製 OBS Browser Source 網址。不想安裝的話，也有純瀏覽器的 Player。

⚠️ 注意

• 推薦模型：Claude Code 用 Opus 5.5、Codex 用 GPT-6.1 Sol。指南說讀像素座標需要很強的視覺能力，換弱一點的模型品質會掉。
• Claude Code 不能產圖：閉眼、嘴型、表情的差分圖只有 Codex 能直接畫。Claude Code 只會幫你準備遮罩和提示詞，要自己拿去其他產圖工具。沒有差分圖時，眨眼和說話只靠網格變形，比較不自然。
• Codex 一鍵版會把插畫和遮罩送到 OpenAI，執行前會先問；加 --no-variants 就全部留在本機。另外它用 --approve-for-me 跑，agent 要在沙箱外執行工具（例如開 Chromium 截圖）時會自動核准，不經過你。
• 攝影機和麥克風的資料都留在本機，傳到直播畫面的只有動作數值。
• 範例角色 Miko 不屬於 MIT 授權，可以用在自己的作品裡修改，但不能單獨轉散佈。
• Rust 原生版本與 macOS 桌面角色還是實驗功能。

🔗 相關：→ 工具-讓LLM產出可驗證的產物（同一個思路：先校準模型能力、用渲染結果檢查自己，不讓模型只靠「看起來對」就回報完成）

---

🤖 AI 開發參考

Claude Cookbooks

網站 · Anthropic 官方 GitHub repo · MIT · ★54k（2026-11-02） · ⬜ 待試

做什麼：Anthropic 官方維護的 notebook 食譜集。每個 notebook 都是一個可以跑的完整範例，示範某種 Claude API 用法或 agent 做法。登記在 registry.yaml 的有 99 篇，日期從 2023-08 到 2026-10。要做某件事前，先來這裡找有沒有官方寫好的範例。

分類導覽（依資料夾，篇數為 2026-10-29 版本）

資料夾	篇數	什麼時候去翻
managed_agents/	17	用 Claude Managed Agents 做代管 agent：資料分析、SRE 事故處理、記住使用者、多 agent 協作、預算上限、版本回滾
misc/	15	API 基本功：批次處理、prompt caching、JSON 輸出、PDF、建評估、產生測資、metaprompt、引用來源
tool_use/	13	工具呼叫的各種做法：程式化工具呼叫、用 embedding 找工具、context 壓縮與清除、記憶工具、平行呼叫
third_party/	13	和 LlamaIndex、LangChain、Pinecone、MongoDB、ElevenLabs、Deepgram 等整合
claude_agent_sdk/	10	用 Agent SDK 做研究、SRE、資安弱點偵測等 agent；部署與從 OpenAI Agents SDK 遷移
capabilities/	7	分類、摘要、RAG（含 contextual retrieval）、Text to SQL、知識圖譜
multimodal/	6	看圖、看圖表與簡報、文件轉寫、zoom 工具看細節
patterns/	5	agent 工作流模式：chaining、routing、平行、orchestrator-workers、evaluator-optimizer
其他	13	skills、extended thinking、可觀測性（OpenTelemetry）、成本最佳化、工具評估、微調

已經收進庫裡的：→ Claude Cookbooks（讀完的 4 篇：工具-agent工作流的基本模式、工具-讓模型寫程式一次呼叫多個工具、工具-agent成本最佳化清單，以及補進 前綴快取 Prompt Caching 的預熱快取）

⚠️ 注意

• 跑 notebook 會花錢：都是真的呼叫 Claude API（有些還要第三方服務的 key）。
• 看日期再照抄：最早的是 2023 年的，部分綁舊模型（例如微調 Claude 3 Haiku）或 beta 功能，參數可能已經改了。照做前先對照官方文件。
• README 的目錄只列了一部分，完整清單看 registry.yaml。

🔗 相關

• AI 技能收藏 —— 裝進 agent 裡用的 skill／plugin／MCP

Link to original

🎯 為什麼存這篇 / 未來想拿它做什麼

• 要用 Claude API 做某件事（批次、快取、工具呼叫、agent）時，先翻這裡有沒有官方範例，再決定自己怎麼寫。
• 這次挑的 4 篇，正好補上庫裡「agent 怎麼組流程、怎麼省 token、怎麼省錢」的缺口。

🧰 這篇給我的工具

• 工具-agent工作流的基本模式 — 一次呼叫做不好、想拆成幾步，不知道該串、分流、平行還是自我修正的時候
• 工具-讓模型寫程式一次呼叫多個工具 — 工具回傳很大、要逐筆查很多資料，token 被塞爆的時候
• 工具-agent成本最佳化清單 — agent 上線後帳單太高，想省錢又怕品質掉的時候
• 補充：前綴快取 Prompt Caching 新增「使用者還在打字時先暖快取」一節，並依官方文件更新讀取倍率與最低長度

✨ 關鍵重點

• 先用固定流程，不夠再升級成 agent：prompt chaining、routing、parallelization、orchestrator-workers、evaluator-optimizer 五種模式，各自對應一種「一次呼叫做不好」的原因。
• 程式化工具呼叫：讓模型寫一段程式在沙箱裡呼叫工具，中間結果不進對話。notebook 的實驗 token 從 110,473 降到 15,919（−85.6%），時間幾乎沒省。
  • ⚠️ notebook 用的 code_execution_20250825 和 beta header 已經過時。官方文件現在規定要 code_execution_20260120 以上，而且不需要 beta header（查證 2026-11-02）。工具卡兩種寫法都列了。
• 成本最佳化要同時看通過率：只看帳單會悄悄掉品質。notebook 用 10 筆保險理賠任務量測每任務成本，再找出「比所有更便宜的設定都更準」的 Pareto 前緣。
• 預先暖快取：notebook 的實驗首字延遲從 20.87 秒降到 1.94 秒。但它是等暖身跑完才開始計時，實際省下的大約是打字時間與 prefill 時間取較短的那個（推論，見快取卡）。
• notebook 都沒有實際執行：會呼叫付費 API。以上數字都是 notebook 裡留下的輸出，部分輸出是舊模型跑的。

💬 原文摘錄

• 官方對 PTC 的提醒：“Do not rely on allowed_callers as a security boundary.”（platform.claude.com 的 programmatic tool calling 文件，查證 2026-11-02）

🔗 相關

• 工具收藏 —— Claude Cookbooks 收藏卡：完整分類導覽與什麼時候去翻
• Agent 記憶設計 —— context 壓力的四種解法表，PTC 是其中一列
• Claude Code 團隊怎麼做程式碼審查 —— 同為 Anthropic 官方的實務文章