怎么在 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 循环就不必每轮重传整段历史。