假设你写了个 agent，跑到第 40 轮，每次调用都要把前面 39 轮、system prompt 和整套工具定义原样再传一遍，API 也要把这一大段重新校验、重新切 token。对话越长，首 token 等得越久。Anthropic 在 11 月 2 日的 API 更新日志 里放出了消息线程，现在还是测试版：第一轮照常发全量，服务端把对话暂存起来，之后每轮只发新消息和上一轮回复的 id。官方文档 说，这样请求更小，首 token 延迟会随着对话变长保持得更低、更稳，最受益的是长时间跑的 agent 循环。
不过在你改代码之前，有两件事先说清楚。第一，它不会让账单变小，文档写明线程不改价格，也不改速率限制。第二，它要把你的对话放在 Anthropic 那边一段时间，这对开了零数据留存（ZDR）的团队是实打实的代价。
第一轮建线程，之后每轮只接上一轮的 id
手写请求的话，线程里每个请求都要带 anthropic-beta: message-threads-2026-08-12 这个头。第一轮跟平时一样，带上完整的 messages、system 和 tools，再加一个 "thread": {"type": "create"}。服务端会把这段对话连同 Claude 的回复存在这次响应的 id 下面。下一轮只发新增的消息，比如用户的新问题，或者回应上一轮 tool_use 的 tool_result，再把 thread 写成 {"type": "continue"}，并把 previous_message_id 设成上一轮回复的 id。
最容易踩的坑是 system 和 tools。它们只能在建线程那一轮发，续接时哪怕传个 null 都会返回 400。另有一组固定字段，每一轮都要用和建线程时一样的值再发一遍。这组字段里最常碰到的是 model、tool_choice 和 thinking。output_config、顶层的 cache_control 和 beta 头的集合也在其中，另外还有 mcp_servers 等几项。哪个值变了，API 就返回 thread_fingerprint_mismatch，错误信息会写出是哪几个字段对不上。max_tokens、stream、service_tier 这类字段每轮可以随便改。想换模型或者改 system prompt，就只能用新设置重新建一个线程。
省事的办法是用 SDK 自带的线程助手。Python 的 2.2.0 和 TypeScript 的 sdk-v1.2.0 在 10 月 23 日加进了消息线程支持。用 client.beta.messages.thread(...) 建一个助手，之后每轮调用 send()，beta 头、续接时去掉 system 和 tools、出错后重发全量，它都替你做。文档里还有一句很容易被忽略：SDK 的 beta 版 tool runner 默认就走线程，建 runner 时可以关掉。下面讲留存时你会知道，这句为什么重要。
线程随时会丢，你手里那份对话才是正本
Anthropic 把线程定位成「尽力而为」。最后一次请求之后 5 分钟线程就过期，每存下一轮回复，这 5 分钟重新计时，最晚在最后一次使用后 1 小时内删掉。更麻烦的是，不管建线程还是续接，响应都不会告诉你这一轮到底存没存上，要等下一次续接才知道。
续接失败会返回 404，error.details.error_code 是 thread_not_found，原因不写。文档列出的情况有一长串：线程过期了；上一轮回复因为工具调用被 max_tokens 截断而没存；上一轮是 fallback 模型写的；上一轮还没生成完；请求来自另一个组织或 workspace；请求来自另一个用户或服务账号，而不是建线程的那个，用旧版 workspace key 建的线程只认那一把 key；新消息里带了存下的对话装不下的东西，比如对话里头一回出现的图片。文档给的恢复办法是从你自己保存的完整对话出发，带上 system 和 tools 重新建一个线程。也有例外：上一轮是 fallback 模型写的，你还可以改在那个 fallback 模型上建新线程；重发之后续接马上又 404，可能是对话太大存不下，这时就不带 thread 直接发。流式输出时，id 在 message_start 里就到了，但要等到 message_stop 再续接，提前发也可能 404。
线程只能往后追加，每个回复的 id 只能被续接一次。想改前面某条消息、从中间分叉，或者 Claude 拒答了，都得重新建线程。所以文档要求你的程序始终保留一份完整对话，从第一天就把重发这条路写好。如果你的 agent 经常停下来等人审批，一等就超过 5 分钟，那么每次恢复基本都要重发全量，线程帮你省的时间也就没了。
模型看到的上下文没变短，你能动上下文的手段反而少了
线程省掉的是上传和预处理，模型读到的东西一点没少。API 在调用模型之前会把整段对话拼回去，上下文窗口照样按完整对话算。
而且线程只能追加，你没法在中途删掉或压缩前面的轮次。9 月进入测试版的按需压缩（compaction）在线程里用不了，请求里带 compaction 参数会直接报 400。上下文编辑也基本不能用，只剩 clear_thinking_20251015 加 keep: "all" 这一种。Token 计数接口和 Message Batches 都不接受带 thread 的请求，要计数就把完整对话拿去算。长对话要瘦身，只能在自己代码里写好摘要，作为一条普通消息塞进新线程。
在 Claude Fable 5.1、Mythos 5.1、Opus 5.5、Sonnet 5.5 和 Haiku 5.5 上，还有一个连带问题：改了 system 或 tools 之后，对话里已有的 thinking 块会失效，用它们建新线程可能报 400。文档的建议是把这些 thinking 块都去掉，代价是模型答新问题时看不到之前的推理。
账单照旧，想省钱还得靠缓存
既然模型读的是完整对话，价格又没改，那么你的 token 账单不会因为开了线程自动变小。文档说得很直接：线程不会替你缓存提示词，缓存放在哪里，还是你自己决定。
最简单的做法是每个请求都带顶层的 "cache_control": {"type": "ephemeral"}。这也是固定字段，每轮要发同样的值。这样每一轮都从缓存里读之前的对话，再把新的一轮写进去。按 定价页，5 分钟缓存的写入是基础输入价的 1.25 倍，命中是 0.1 倍，Opus 5.5 和 Sonnet 5.5 命中只要 0.05 倍，Fable 5.1 和 Mythos 5.1 更低，是 0.025 倍。以 Opus 5.5 为例，输入每百万 token 4 美元，缓存命中每百万 token 0.20 美元。长对话里反复读的那一大段，真正省钱的是这里，不是线程。
手动放断点要注意上限。带 thread 的请求最多 4 个 cache_control 断点，顶层那个算一个，建线程时放在 system 和 tools 上的断点每次续接都要再算一遍，超出一个就是 thread_unsupported_request。还有一个巧合可以留意：线程空闲 5 分钟过期，默认缓存 的寿命也是 5 分钟，agent 一旦停顿太久，两样往往一起失效。好消息是，文档列出的那几种线程错误都在模型运行前返回，不消耗 token。
数据留存的代价落在开了 ZDR 和 HIPAA 的组织头上
线程里存的是发给模型的完整对话、建线程时的 system 和 tools，外加一份固定字段的指纹。文档说，这些内容只放在内存里，用服务端管理的密钥加密，不写入持久存储，最晚在最后一次使用后 1 小时内删除。文件只存引用，所以线程用着的时候，对话引用的文件你得一直留着。目前没有任何接口可以列出、读取或删除线程，你没法提前清掉，只能等它自己过期。
在 API 数据留存页 的表里，消息线程的 ZDR 和 HIPAA 两栏都写着「不符合」。两种组织的结果不一样。开了 HIPAA 的组织直接用不了，请求会被拒。开了 ZDR 的组织，API 不会拦你。按这一页的说法，用了不符合 ZDR 的功能，就等于你选择让这部分数据走出 ZDR，按这个功能自己的留存规则处理。Anthropic 也写了，用线程不影响你使用其他符合 ZDR 的功能。
所以真正要提防的是不知不觉就用上了。如果你的组织有 ZDR 协议，升级 SDK 之后跑 beta 版 tool runner，它默认就会建线程。对没签 ZDR 的组织来说，Anthropic 隐私中心 7 月 1 日版写的标准做法是 API 的输入输出在 30 天内删除，线程在内存里多放这一个小时，几乎不改变什么。
文档没讲清楚的地方有这么几处：续接时存在服务端的那部分对话在 usage 里怎么计，文档只说价格不变；多大的对话算「太大存不下」，没给数字；测试版什么时候结束，没说；tool runner 从哪个 SDK 版本开始默认用线程，发布说明里也没找到。支持的平台列了 Claude API、Claude Platform on AWS、由 Anthropic 托管的 Google Cloud 版和 Microsoft Foundry，Amazon Bedrock 不在里面。
如果你的 agent 对话很长、每轮间隔只有几秒到几十秒、组织也没签 ZDR，可以先用 SDK 助手加上顶层 cache_control 试一试，盯两个数：首 token 延迟和重发全量的次数。如果你签了 ZDR 或开了 HIPAA，先去代码里搜一下 thread 和 tool runner，确认没在你不知道的地方把对话交出去。
