Anthropic 11 月 2 日公测 Messages API message threads 之后,create 和 continue 的请求 JSON 该怎么写?

截至 2026 年 11 月 3 日:beta 头 message-threads-2026-08-12;thread create 带全量 system/tools,continue 只发增量 messages 与 previous_message_id。5 分钟过期、thread_not_found 需 replay。

先给结论: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,错误信息会点名不一致字段。

类别createcontinue
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 模板上。

  • JSON 校验 — 检查 turn2 是否误带 system。
  • JSON Diff — 对比 replay 前后 create 包是否一致。
  • JSONPath — 例如从响应取 $.id 写入下一轮模板。

常见问题 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 或显式错误码分支。