先给结论: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 或显式错误码分支。