怎麼在 Claude API 裡用 Message Threads（公測）跑長會話 Agent

跑長會話 agent 時，Messages API 請求裡往往堆著 system、工具定義、tool 結果和多輪對話。沒有 message threads，下一輪常常要把整段歷史再傳一遍，請求體越來越大，首 token 等待也會被拖長。Anthropic 在 2026 年 11 月 2 日的釋出說明裡公開了 Messages API 的 message threads（公測）：create 之後由服務端保管對話，continue 只需帶上新增消息。

下面按官方文件整理接入步驟，面向 Messages API 的 thread 欄位，適合自己拼請求或接 SDK 的開發者。它和 Managed Agents 的 session threads 不是一回事，不要把兩套會話概念混用；message thread 也不會替你做 prompt caching——服務端只是為 continue 保留對話狀態，需要快取時仍要自己設 cache_control。文中示例來自官方文件原文，並標明未執行。

先分清 create 和 continue

create 接近你今天的常規 Messages 呼叫：帶上當前完整對話，以及要用的 system、tools，再加：

"thread": {"type": "create"}

介面會把對話（含 Claude 本輪迴復）存到該響應的 id 下。響應裡沒有單獨欄位宣告“已存檔”，能不能繼續，要看下一輪 continue。

continue 只傳自上一響應以來的新 messages，並帶：

"thread": {
  "type": "continue",
  "previous_message_id": "<id of the previous response>"
}

continue 不要再帶 system 或 tools——執行緒沿用 create 時的值。就算寫成 null 也會 400。

執行緒裡每一輪請求都要帶 beta 頭 message-threads-2026-08-12（cURL 為 anthropic-beta: message-threads-2026-08-12；Python 示例為 betas=["message-threads-2026-08-12"]）。

哪些欄位每輪必須一樣

文件把欄位分成三類：

MCP 的 URL、授權 token、container 的 id 不會被執行緒儲存。要用就在相關請求裡繼續傳 mcp_servers / container。要改僅 create 或固定欄位，只能新開 create，並重傳完整對話和新值。

執行緒是隻追加的：每個響應 id 只能 continue 一次，務必從最新 id 繼續。要改歷史或開分支，重新 create。

歷史仍歸你管，過期就整段重放

執行緒還有效時，continue 只送新消息，不是每輪完整 history。新消息通常是下一輪 user，或回應上一輪 tool_use 的 tool_result。不要把介面已有的消息再貼一遍，可能重複進對話或直接報錯。若響應以 stop_reason: "pause_turn" 結束，用該響應 id 發 messages 為空陣列（"messages": []）的 continue；若 404，就把含暫停響應在內的完整對話放進新的 create。

應用才是真相源：本地保留完整副本，並一開始就準備好 replay。跨程序就要自己持久化。官方 SDK 的 thread helper 可在 helper 物件存活期間放記憶體副本並代做 replay，但替代不了你自己的落盤。

continue 因執行緒失效失敗時（常見 404 thread_not_found），用新的 create 整段重傳（含 system / tools），再從新響應 id continue。

過期、刪除，以及查不到的執行緒

• 閒置過期：上次請求後 5 分鐘；每次成功存下的響應會重啟這 5 分鐘。
• 刪除：上次使用後 不超過 1 小時刪除。
• 沒有 list / read / delete thread 的 API。

執行緒放在記憶體裡、用服務端金鑰加密，不落 durable storage，不支援 ZDR。啟用 threads 本身不改變你對其它 ZDR 功能的使用宣告；組織策略仍以官方保留說明為準。

模型跑起來之前就可能返回的錯誤包括：thread_not_found（改用 create 重放）、thread_fingerprint_mismatch（固定欄位漂了）、thread_already_continued（該 id 已 continue 過）、thread_continue_in_flight（同一 id 上還有 continue 在跑）、thread_unsupported_request（功能或組織設定不允許配 threads）。

平臺、價格和不支援的組合

可用平臺包括：Claude API；Claude Platform on AWS；Claude Models on Google Cloud（Anthropic managed）；Claude in Microsoft Foundry。文件 Availability 寫的是所有模型可開 beta；示例裡的 model id 只是當日文件頁上的樣例，不要當成永久白名單，也不要用它推斷未出現在文件裡的限制。

threads 不改變定價或速率限制。廠商同時說明 token 用量不變：HTTP 請求體變小，不等於少計費——模型每輪仍讀完整對話。若你關心帳單，需要另查定價與快取策略，不能把 threads 理解成自動減計費的開關。

不支援的組合（節選）包括：帶 thread 的 Message Batches；帶 thread 的 token counting；與 threads 一起用的 on-demand compaction；多數 context editing；已開 HIPAA readiness 的組織；已開 Inference hooks 的組織。命中時常見 400 thread_unsupported_request。接到不認識的 unsupported 細節時，可先去掉 thread、改回整段重傳，再對照當日文件。

官方 create / continue 示例

以下樣例從 Claude Platform 的 message threads 文件原樣摘錄並標明未執行；需要 API key，執行會消耗配額。文件樣例使用其中的 anthropic-version: 2026-10-21 與 model id claude-opus-5-5。

cURL

# Turn 1: send the full conversation and create a thread
curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "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"}
  }'

# Turn 2: send only the new message. Set message_id to the id of the turn 1 response.
# Leave out system and tools: the thread keeps them.
curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "messages": [{"role": "user", "content": "How long does standard shipping usually take?"}],
    "thread": {"type": "continue", "previous_message_id": "'"$message_id"'"}
  }'

Python（beta Messages create）

client = anthropic.Anthropic()

# Turn 1: send the full conversation and create a thread
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    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"},
    betas=["message-threads-2026-08-12"],
)

# Turn 2: send only the new message and the id of the turn 1 response.
# Leave out system and tools: the thread keeps them.
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    messages=[
        {"role": "user", "content": "How long does standard shipping usually take?"}
    ],
    thread={"type": "continue", "previous_message_id": first.id},
    betas=["message-threads-2026-08-12"],
)

for block in second.content:
    if block.type == "text":
        print(block.text)

按同頁文件走 Anthropic Python SDK 的 beta Messages 路徑即可。這裡不另釘最低 SDK 版本，以當日官方文件為準。

關於 35% TTFT 那句話

產品文寫的是：多數 Claude Code 使用者預設開啟 message threads 時，500k–1M token 的請求 median TTFT 約降 35%；同時 token 用量不變。按廠商條件轉述即可，不要引申成降低帳單或少計費 token。

相關閱讀

排查 Messages API 其它請求欄位時，可看 Claude API 傳 temperature 報 400（2026-10-21）——那是 temperature／API 版本問題，不是 threads。價目與限額見 Claude API 價格（2026 年 10 月）；那是另一份快照，threads 不會改寫那張價表。

接入檢查清單

動手接線前，可以按下面順序自檢，避免把“配置寫進去了”當成“執行緒一定還活著”：

1. 每輪 create／continue 都帶 message-threads-2026-08-12。
2. create 送全量 messages 與 system／tools，儲存響應 id。
3. continue 只送新 messages 與 previous_message_id，不要再送 system／tools。
4. 固定欄位整條執行緒保持一致；要改 model 或 system，就新開 create。
5. 自己持久化完整對話；404 後用新 create 重放，而不是空等執行緒“自動恢復”。
6. 按 5 分鐘閒置過期、1 小時內刪除來設計重試與落盤；沒有 list／read／delete API。
7. 不要和 Message Batches、帶 thread 的 token counting 等不支援組合硬拼。

之後若文件新增欄位，以當日 Claude Platform 文件為準。把 beta 頭和 create／continue 形狀接對，長 agent 迴圈就不必每輪重傳整段歷史。