Claude Message Threads API 指南（2026 年 11 月）

對於動輒累積數十萬 Token 的 agent 迴圈，反覆上傳完整對話歷史一直是延遲來源。Anthropic 在 2026 年 11 月 2 日以公開測試版推出 message threads：面對 50 萬至 100 萬 Token 的請求，中位數首個 Token 時間約可縮短 35%，但 Token 帳單完全不變。這是改善傳輸效率的功能，而非省 Token 的方案；而且它有嚴格的 5 分鐘閒置期限。

Threads 解決傳輸延遲，不會減少 Token 計費

Message threads 是 Messages API 的暫時性伺服器端對話狀態，於 2026 年 11 月 2 日以公開測試版推出。第一次請求透過 thread: { "type": "create" } 傳送完整歷史紀錄；後續則以 thread: { "type": "continue" } 搭配 previous_message_id，只傳送新增內容。依據 Anthropic 的公告與平台文件，狀態會保留在加密記憶體中，不會寫入磁碟；閒置 5 分鐘後過期，最後一次使用後最晚 1 小時內刪除。

Thread 中的每一筆請求都必須帶上 beta header：anthropic-beta: message-threads-2026-08-12。價格與速率限制均未改變：Claude 每一輪仍會讀取完整對話，因此輸入與輸出 Token 的計費相同，只是你實際上傳的資料量會少很多。

「很好啊，但它不會降低 Token 成本 :( Claude 每一輪仍會讀取整段對話，Token 用量也沒有改變」 — @_navicstein，回覆官方發布串文

官方公告指出，50 萬至 100 萬 Token 的請求其中位數 TTFT 約降低 35%，但沒有任何 Token 折扣。

Threads 與 prompt caching：差異其實很簡單

Threads 減少的是你要傳送的內容；prompt caching 減少的則是你需按原價支付的內容。Threads 不會自動啟用任何快取，仍須自行設定 cache_control 斷點。以下快取互動細節依據實作解析：每次 continue 都應保留頂層 cache_control，快取讀取費用為基本輸入價格的 0.1 倍；Claude Opus 5.5 與 Sonnet 5.5 則為 0.05 倍。

別和 managed-agent session threads 混為一談

搜尋結果常把兩種不同的「threads」混在一起。本文討論的是 Messages API message threads：它是短暫的請求大小最佳化機制，沒有列出、讀取或刪除的 API。Managed-agent session threads（GET /v1/sessions/{session_id}/threads/{thread_id}）則是 Anthropic managed-agents API 裡的執行 thread，提供列出、取得與封存端點。如果文件提到 child threads、event streams 或 archiving，看的就是另一套 API。可參考 session threads API 參考文件，確認自己需要的是哪個介面。

Anthropic 的 message threads 公告頁面，介紹供長時間運行 agent 使用的伺服器端對話狀態

Thread 的實際流程：建立、延續與過期

實務上，thread 是只能追加的資料流：先帶完整上下文建立、後續只傳遞增量，狀態遺失時則完整重播。它沒有分支、編輯、倒轉或檢視 API。每次回應都會產生新的 id，而每個 id 只能拿來 continue 一次。本節的欄位與錯誤規則，依據平台文件及實作解析整理。

建立 thread 時需帶上完整內容：完整 messages、system、tools，以及：

{
  "model": "claude-opus-5-5",
  "system": "You are a support agent for Acme. Keep replies short.",
  "messages": [{ "role": "user", "content": "Hi! I have a question about an order." }],
  "thread": { "type": "create" }
}

Continue 時只傳遞新增內容，通常是使用者訊息或 tool_result 區塊：

{
  "model": "claude-opus-5-5",
  "messages": [{ "role": "user", "content": "How long does standard shipping usually take?" }],
  "thread": { "type": "continue", "previous_message_id": "msg_xxx_from_create" }
}

Continue 時不要傳送 system 與 tools；即使是 "system": null 也會觸發 400。串流回應必須等待 message_stop 後才能 continue；可用於延續的 ID 會在 message_start 時送達。

Thread 進行中哪些欄位能修改？

Anthropic 會為 create 請求中的部分內容建立指紋。更動受指紋保護的值會回傳 thread_fingerprint_mismatch，只能另開一條 thread。

類別	範例	Continue 時的規則
僅限建立時	`system`、`tools`	絕不可重送；`null` 同樣會失敗
固定不變	`model`、`tool_choice`、`thinking`、`mcp_servers`、`context_management`、`output_config`、container skills、頂層 `cache_control` 的處理方式	必須維持完全一致
可自由調整	`max_tokens`、`stop_sequences`、`stream`、`metadata`、`service_tier`	每一輪都可變更
每次都要重送	MCP server URLs / auth tokens、`container` ID	伺服器端不會保存，使用時每次都要附上

使用 extended-thinking 模型時要格外注意：編輯 system 或 tools，可能會使先前的 thinking / redacted_thinking 區塊失效。若過期後完整重播回傳 400，應從重播歷史中移除過時的 thinking 區塊，而不是原封不動地重試。

5 分鐘過期機制：重播備援不能省

應把 threads 視為盡力而為的機制。完整歷史、system、tools 與檔案參照都必須保留在本地端，因為只有下一次 continue 成功，才代表狀態確實被保存。檔案以參照形式持有，若 thread 尚未結束就刪除檔案，continue 會失敗。

每次保存成功的回應都會重設過期計時。閒置 5 分鐘後，下一次 continue 會回傳 404；此時必須以完整對話重新發出 create。資料會在最後一次使用後最晚 1 小時內消失。

HTTP	代碼	發生原因	處理方式
404	`thread_not_found`	已過期、尚未保存、key/workspace 錯誤、在純文字 thread 中第一次加入圖片、由 fallback model 處理，或回應仍在生成	確認 key/workspace 與設定後，以新的 `create` 重播完整歷史
400	`thread_fingerprint_mismatch`	固定欄位被更動	還原原始值，或建立新 thread
400	`thread_already_continued`	該 `previous_message_id` 已被使用過	從最新的 `id` 繼續
400	`thread_continue_in_flight`	同一 ID 有並行的 continue 請求	等待它完成後使用新的 ID，否則重播
400	`thread_unsupported_request`	使用不支援的設定，例如超過 4 個快取斷點或 batches	移除該設定，或不使用 thread 傳送

依文件摘要，失敗的 thread 請求發生於模型執行之前，因此不會消耗 Token，也不會重設過期計時。在接受下一輪輸入前，應以原子方式保存最近一次成功回應的 ID；如果工具操作有副作用，重播流程也必須做好冪等性防護。

Python 重播範例（僅處理已確認的 thread_not_found；指紋、並行與不支援請求錯誤都需要個別分支處理）：

try:
    resp = client.beta.messages.create(
        model="claude-opus-5-5",
        messages=[new_msg],  # delta only
        thread={"type": "continue", "previous_message_id": last_id},
        extra_headers={"anthropic-beta": "message-threads-2026-08-12"},
    )
except NotFoundError:  # thread_not_found after checking identity/config
    resp = client.beta.messages.create(
        model="claude-opus-5-5",
        system=SYSTEM, tools=TOOLS,
        messages=full_history + [new_msg],  # you stored this
        thread={"type": "create"},
        extra_headers={"anthropic-beta": "message-threads-2026-08-12"},
    )

Proxy 與 key 輪替造成的 404 陷阱

以下是營運者回報、尚未寫入官方文件的行為：thread 會綁定建立它的 organization、workspace 與 credential。若轉送服務每個請求都輪替 API key，便可能用 key A 建立、再用 key B continue，呈現出的結果與過期完全相同：不斷收到 404，只好完整重播，延遲優勢也隨之消失。

「thread 绑定创建它的 key 和 workspace，换 key 会 404 thread_not_found。中转站轮换 key 会先吃 404 再全量重发。」 — @ak12kpoot（關於 proxy 行為的中文開發者筆記）

請將一條 thread 固定使用同一把 key，或在共用 key 的路由上停用 threads。

支援平台、限制條件，以及現在是否值得導入

Message threads 可用於 Claude API、AWS 上的 Claude Platform、Anthropic 管理的 Google Cloud Claude Models，以及 Microsoft Foundry 中的 Claude。公開測試期間涵蓋所有模型，沒有另外的模型白名單，也未提及候補名單。

規劃導入時，更值得注意的是以下不支援項目：

範圍	狀態
Amazon Bedrock	不支援
Message Batches	不支援，批次中的 thread 項目會失敗
Token counting endpoint	不支援，需自行計算完整歷史
Compaction / context editing	不支援，僅 `clear_thinking` 搭配 `keep all` 例外
Zero data retention、HIPAA-ready、inference hooks	不符合資格
Thread management API	沒有，無法列出、讀取或刪除 threads

導入前快速判斷

現在就適合用：活躍的 coding agents、帶有截圖的 computer-use 迴圈，或文件量大、在 5 分鐘間隔內進行數十輪操作的流程。請搭配 prompt caching 與重播路徑。
暫時先跳過：人類節奏的聊天、可暫停的工作流、批次管線、ZDR/HIPAA 工作負載，或 Bedrock 部署。
同時使用的注意事項：每一筆請求頂層的 cache_control 都會計入 4 個斷點上限；create 時 system/tools 中的斷點，也會在每一次 continue 時再次計入。超出上限會回傳 thread_unsupported_request，因此兩者併用前應先整併斷點。

延伸閱讀：Claude API pricing guide 2026、Claude Skills API guide。

常見問題

需要哪些 beta header 與參數？

Thread 中的每一筆請求都要傳送 anthropic-beta: message-threads-2026-08-12。第一次呼叫加上 thread: { "type": "create" }；之後則使用 thread: { "type": "continue", "previous_message_id": "<last response id>" }。

Thread 過期後會怎樣？

下一次 continue 會回傳 404 thread_not_found。請將完整 messages 加上原本的 system/tools，作為新的 create 重新傳送。閒置 5 分鐘即過期，最後一次使用後最晚 1 小時內刪除。

可以列出、檢視或刪除 threads 嗎？

不行。Messages API threads 沒有管理 API，本地端保存的歷史紀錄才是唯一的永久記錄。

Amazon Bedrock 支援嗎？

不支援。可用的平台是 Claude API、AWS Claude Platform、Microsoft Foundry 與 Anthropic 管理的 Google Cloud。Bedrock 請求應維持傳送完整歷史。

可以在 thread 中途修改 system prompt 或 tools 嗎？

不行。必須以新的 system/tools 建立新 thread。在 continue 時傳送變更過的值會觸發 thread_fingerprint_mismatch。model、tool_choice 與 thinking 設定也是如此。

支援 streaming、tools 與 MCP 嗎？

支援，但有幾項規則：continue 前必須等待 message_stop；每一輪都要重送 MCP URLs/tokens 與 container IDs；fallbacks 則要每次請求都傳送，或完全不要傳送。由 fallback model 生成的回應不會被保存，必須重播。