Claude Message threads怎么接入？增量消息、过期重放与参数核对

长会话每轮重传全部消息会增加传输与预处理开销。Anthropic在11月2日公布Message threads公开测试，客户端首轮发送完整内容，后续只发增量消息和上一响应ID。它减少上传与首字延迟，不减少模型实际读取的上下文，也不自动降低Token用量。本文用两轮练习说明接入与恢复，不实际调用付费API。

第一步：准备支持线程的Messages客户端

该能力目前为测试功能，使用message-threads-2026-08-12 beta header，官方原生API及列出的托管平台支持情况以文档为准。线程不符合ZDR与HIPAA资格；先确认组织允许使用，不为教程改变既有数据策略。客户端仍需保存完整消息，不能把服务端短暂内存当永久聊天数据库。

线程闲置五分钟到期，官方在最后使用后一小时内删除相应内存内容。即使响应正常，也不保证该轮已被存成可续接线程，下一轮才可能发现不可用。应用要从一开始就设计重放，而不是上线后才发现丢了历史消息。

第二步：首轮创建线程

import anthropic

client = anthropic.Anthropic()
betas = ["message-threads-2026-08-12"]
history = [{"role":"user","content":"练习：记住项目代号为海星。"}]
first = client.beta.messages.create(
    model="claude-opus-5-5", max_tokens=256,
    system="仅回答练习问题，不调用工具。",
    messages=history, thread={"type":"create"}, betas=betas,
)
history.append({"role":"assistant",
                "content":[b.model_dump() for b in first.content]})

环境中的API认证由已配置客户端读取，不把密钥写进代码。模型示例来自当前官方文档，使用前确认账号权限。保存完整响应内容块与ID，而非只摘取显示文字，复杂工具循环还涉及其他内容块。本练习不使用工具、缓存或后备模型，先把最小续接路径验证清楚。

第三步：仅发送新增用户消息

new_turn = {"role":"user","content":"刚才的项目代号是什么？"}
history.append(new_turn)
second = client.beta.messages.create(
    model="claude-opus-5-5", max_tokens=256,
    messages=[new_turn],
    thread={"type":"continue","previous_message_id":first.id},
    betas=betas,
)

续接不再发送system或tools，连null也不应发送；model、thinking、tool_choice等固定字段以及beta集合须与创建时一致，max_tokens等自由字段可按规则变化。把全部旧消息再次传入continue可能重复追加或报错，不能把create与continue使用同一个无差别请求体。

每次成功后记录最新响应ID，下一轮从它续接，每个ID只能续接一次。并发用户消息应由应用顺序处理，不能两个工作进程同时从旧ID分叉。流式场景需等message_stop才使用响应ID，不在message_start出现时立刻开启下一轮。

第四步：针对错误做完整重放

404先检查error.details.error_code。确为thread_not_found时，用本地完整历史、system与tools重新create，再从新响应ID继续；无效模型也可能404，不能一见404就盲目重放。400的thread_fingerprint_mismatch应检查固定参数，不用反复重试来掩盖配置错误。

恢复策略示意：
1. 持久化本地会话与待提交的新消息。
2. 正常走continue。
3. 确认thread_not_found后，用完整历史走create。
4. 保存新响应及ID，后续改用新ID。
5. 若仍无法保存线程，按文档退回普通完整Messages请求。

SDK线程辅助对象可管理部分重放，但它只在进程内存保留副本，进程结束仍需你自己的持久化。不要在网络错误时无限创建同一业务操作；若模型工具会修改外部系统，应用还要单独处理工具执行幂等，线程机制不会替你撤销外部动作。

第五步：验收会话一致性而非只看速度

用练习代号检查第二轮回答，再模拟线程过期和参数变化，观察是否进入正确恢复分支。确认没有重复用户消息、丢失助手回复或跨用户串线。本文示例只做语法示范，未发出模型请求，不虚报延迟测试结果。

线程不自动建立Prompt caching，计价与限额仍沿用现有规则。先证明增量请求、历史副本和恢复路径正确，再用真实受控测试测首字延迟；不要把公告里的总体数据当成自己应用一定达到的提升。

官方资料

资料核对日期：2026年11月7日。

• Anthropic：Message threads文档
• Anthropic：11月2日公告