先給結論:2026 年 11 月 2 日 Anthropic 把 Messages API 的 message threads 推到公測。每次請求帶 anthropic-beta: message-threads-2026-08-12;首回合在 JSON 里加 thread: {type: create} 並照常帶上完整 messages、system 與 tools;後續回合只發新增 messages,並用 thread: {type: continue, previous_message_id} 指向上一條響應的 id,且不要再傳 system/tools。響應形狀仍是普通 message JSON。執行緒在最後一次請求後約 5 分鐘過期,最晚約 1 小時刪除;continue 失敗時看 error.details.error_code 是否為 thread_not_found 再決定是否全量 replay。
這篇按 2026 年 11 月 3 日寫,依據發行說明與《Message threads》檔案。昨天本站寫過《ChatGPT Pro/Business API 贈金》——那邊是組織餘額;這邊是請求體 JSON 從「整段歷史」變成「增量 + 指標」。十天前《128 MB 上限》解決「能發多大」;threads 解決「長對話/agent 迴圈不必每輪重傳整包」。
create 與 continue 的 JSON 長什麼樣
公測仍走 POST /v1/messages(或 SDK 的 beta.messages.create)。與無 thread 的差別只在頂層多一個 thread 物件:
// Turn 1 — create
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": "You are a support agent.",
"messages": [{"role": "user", "content": "Hi, order question."}],
"thread": {"type": "create"}
}
// Turn 2 — continue(無 system / tools)
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "How long is standard shipping?"}],
"thread": {
"type": "continue",
"previous_message_id": "msg_01..."
}
}
在 continue 請求裡帶上 system 或 tools(哪怕 null)會 400。服務端用 create 時存的副本補全上下文。第一方 Claude API、Claude Platform on AWS、Anthropic 託管 Google Cloud、Microsoft Foundry 檔案均列出支援;Bedrock 等平臺若未上線,仍按全量 messages 整合。
previous_message_id 填哪個 id
欄位名是 previous_message_id,值是上一輪完整響應頂層的 id(例如 msg_...),不是某條 messages[] 裡的自定義 id。每一輪 continue 都應指向緊鄰上一回合的響應 id;檔案要求每個響應 id 只能被 continue 一次,分支對話應 fork 新 thread 或改走全量 create。
響應 JSON 結構不變:仍有 content、stop_reason、usage 等。你的應用仍應本機持久化完整對話——API 不會在 create/continue 響應裡宣告「這一回合是否已成功寫入 thread」;只有下一次 continue 成功或 404 才知道。
每輪都要重複的固定欄位
除 create-only 的 system/tools 外,model、tool_choice、thinking、output_config、頂層 cache_control、以及 create 時宣告的 anthropic-beta 集合等必須在每一輪保持一致。變更會 400,error_code 常為 thread_fingerprint_mismatch,錯誤資訊會點名不一致欄位。
| 類別 | create | continue |
|---|---|---|
| system、tools | 傳送 | 省略(傳送即 400) |
| model、thinking、cache_control 等 | 傳送 | 同 create 值再發 |
| messages | 完整到當前 | 僅自上一響應後的增量 |
帶 thread 的請求最多 4 個 cache_control 斷點;超出會 thread_unsupported_request。Prompt cache 規則與無 thread 時不同:create 上打在 system/tools 的斷點會在後續 continue 重複計數。
5 分鐘 TTL 與 404 replay
執行緒是 best-effort:每次成功儲存的響應會把 5 分鐘 idle 計時重置;資料加密駐記憶體、不落盤,最晚在最後一次使用後約 1 小時內刪除。continue 若返回 404,先讀 error.details.error_code:
thread_not_found— 過期、上一回合未儲存(如max_tokens截斷的工具呼叫)、或 id/金鑰/workspace 不一致等。用本機完整副本重新thread: create,再從新響應 id continue。- 模型不存在等其他 404 — 不要誤當 replay。
Python/TS SDK 的 beta.messages.thread() helper 會在 404 時自動 replay,並可在 thread_unsupported_request 時配置 continue_unthreaded 退回無 thread 全量傳送。Token Counting 請求不能帶 thread,應對完整對話計數。
工具呼叫、pause_turn 與流式
工具回合:continue 的 messages 通常以含 tool_result 的 user 訊息接續上一響應的 tool_use。若 stop_reason 為 pause_turn,應對該響應 id 發 messages: [] 的 continue,而不是新 user 文字。
流式時響應 id 在 message_start 就出現,但必須等到 message_stop 再 continue,否則可能 404。Beta tool runner 預設也用 thread,可用 thread=False 關閉。
本機校驗 thread JSON 時注意什麼
在 CI 或編輯器裡校驗請求體時,建議為 create/continue 各維護一份 JSON Schema 變體:continue 禁止 system/tools 鍵;thread.type 列舉 create|continue;continue 必填 previous_message_id 字串。合併多環境配置時不要把「無 thread 的歷史陣列」直接套到 continue 模板上。
常見問題 FAQ
message threads 和 Claude Managed Agents 的 session threads 一樣嗎?
不一樣。檔案明確 message threads 是 Messages API 上的短期服務端狀態;Managed Agents 的 session 是另一套產品概念。
continue 可以省略 anthropic-beta 頭嗎?
不行。thread 的每一回合都要帶 message-threads-2026-08-12,且 beta 集合需與 create 時一致。
128 MB 上限和 threads 衝突嗎?
不衝突。threads 減的是重複上傳與校驗;單回合 payload 仍受平臺位元組上限約束,超大對話可能無法儲存 thread。
能否在 thread 裡做 compaction 摘要替換歷史?
thread 僅追加。要壓縮上下文,應把摘要作為普通 user 訊息開新 create thread。
API 版本 2026-10-21 還要單獨升級嗎?
threads 是 beta 能力,與 anthropic-version 遷移正交;新 SDK 預設 2026-10-21,但檔案示例仍常見 2023-06-01,以你 SDK/平臺組合為準。
響應裡會多 thread_id 欄位嗎?
不會。鏈路靠每條響應的 id 串聯;沒有額外 thread UUID。
總結
11 月 2 日的 message threads:用 create/continue JSON 換更小的後續請求與更穩的 TTFT,但你要自己存全量歷史並處理 404 replay。校驗工具適合抓 continue 誤帶 system;生產 agent 更推薦 SDK thread helper 或顯式錯誤碼分支。