ClaudeMessages APIConversation StateAgent

Claude 的 message thread 只有几分钟,长会话还得自己保存

Messages API 新增的 thread 能省去重复上传历史,但它会过期、受固定字段约束,也不自动开启缓存。用两轮请求说明创建、续接与 404 后的重建。

查看接入文档
Claude 的 message thread 只有几分钟,长会话还得自己保存

一个 Agent 连续调用几十次工具,每轮都把之前的消息重新上传,会重复传输和处理大量相同内容。Claude 在 11 月 2 日推出 beta 的 message threads,让后续请求只发新消息,再引用上一条响应的 ID。

但这份服务端会话只是短期便利:最后一次请求后闲置 5 分钟会过期,最迟在最后一次使用后 1 小时内删除。 应用仍需自己保存完整历史,才能在进程重启、thread 丢失或需要改配置时继续工作。

本文于 2026 年 11 月 16 日核对当前官方文档。下文针对官方 Claude API,beta header 是 message-threads-2026-08-12;它也不同于 Managed Agents 的 session threads。请求样例只做离线语法检查,没有用真实账号执行或验证第三方渠道支持。

创建时给全量,续接时只给新增

第一次请求仍然包含完整的 messages、system 和 tools,额外加上:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "system": "Use only the public demo policy supplied by the user.",
  "messages": [
    {"role": "user", "content": "Demo policy: unopened items can be returned within 7 days. Summarize it."}
  ],
  "thread": {"type": "create"}
}

把它作为请求体发往官方 POST https://api.anthropic.com/v1/messages,使用自己的官方凭据与所需版本头,并加上上述 beta header。拿到完整响应后,把原请求与完整 assistant content 保存下来。第二轮只发送新增内容:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Does that demo policy mention customized items?"}
  ],
  "thread": {
    "type": "continue",
    "previous_message_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"
  }
}

演示政策没有提定制商品,预期应说明资料不足;本文没有实际取得该回答。每轮改用最新响应 ID,不能反复引用最初那条。continue 也不能再次夹带上一轮 assistant 响应,它已在服务端历史里。

首次发送全量历史,后续只发送新消息与最新响应 ID

这减少了上传内容,不代表模型只看新消息。API 会重建完整会话再调用模型;它也不会自动启用 prompt caching。线程复用和缓存分别配置,缓存概念可参照输入缓存与费用说明,具体 Claude 参数仍以本篇官方来源为准。

什么可以改,什么要重开

续接时,system 和 tools 必须省略,连传 null 都会报错。model、thinking、tool_choice、output_config 等属于固定字段,要保持创建时的值;beta header 的集合也属于固定部分。max_tokens、stream 等字段则可以变化。

想做的事当前规则
继续用户提问或回传工具结果只追加新增消息,使用最新响应 ID
调整输出上限或流式开关可以在后续请求调整
更换模型、初始指令或工具定义用本地全量历史创建新 thread
回到早先一轮分支创建新 thread,不能让同一个响应 ID 续接两次

固定字段改变会出现 thread_fingerprint_mismatch。同一个响应 ID 只能续接一次,因此同一 thread 的调用要按顺序执行。若业务需要分支,让每个分支持有自己的历史与新 thread。

修改 system、tools 再重建时,还要处理旧 thinking 的前缀约束,不能只更换 thread ID。Fable 思考块的历史绑定解释了为什么改过的历史可能仍然报 400。

遇到 404,先确认是 thread 丢了

模型不存在也可能返回 404。先检查 error.details.error_code 是否为 thread_not_found,不要把所有 404 都送进“重建历史”的循环。

确认后,用本地副本恢复完整会话,带上原来的 system 与 tools,再发一次 thread.type: create。完整副本包含已经收到的 assistant 内容与工具结果,不需要重新执行已经完成的工具。重建成功后改用新响应 ID。

确认 thread_not_found 后,从应用历史重建,工具完成记录另外保留

过期只是原因之一。API 可能没有存下某轮,上一轮仍在生成,或请求身份与工作空间发生了变化;错误本身不会告诉你是哪一种。官方 SDK helper 会在这类 404 后尝试一次全量重建,但它保存的历史只存在 helper 对象内存中,不会替应用持久化。

业务工具还需要独立记录完成状态。模型会话恢复不等于订单、消息或文件写入可以重做,有副作用的工作流恢复给出了这层区分。

收到响应 ID,还不能马上发下一轮

流式响应会在 message_start 中给出 ID,必须等到 message_stop 才从它续接。提前续接可能得到 404。一次正常响应也不保证它已被服务端保存;应用是在下一次续接时才知道能否复用。

最小验收可以分别覆盖:正常两轮、闲置过期后的重建、进程重启后的恢复、固定字段改变、流中断以及已执行工具不重复。只用公开测试数据;敏感正文和可用凭据不进入求助日志。

两轮调用、过期、重启和流结束分别验证,不能只看首轮成功

thread 内容保存在加密内存中、不写入持久存储,但该功能仍标记为不符合 ZDR 资格,不要把“短期内存”直接当作零保留承诺。通过 Nbility 接入时,先按Claude 原生兼容说明确认渠道能处理 thread、beta header 和续接语义;本文未验证该能力,已有 Messages 调用可用不足以证明 threads 可用。同一批发布里还有一条更容易被忽略的变化:受支持的模型会给输出加文字水印,thread 里保存的内容同样由模型生成。

相关文章

用 Nbility 跑通你的 Agent 工作流

获取 API Key,统一接入 OpenAI 兼容模型和开发工具。

获取 API Key