Claude API message threads:只需发送新消息

Anthropic 推出了 Claude API message threads 的测试版:对话会在服务器端短暂保留,之后的每次请求只需发送新消息。该功能于 11 月 2 日出现在 Claude Release Notes 中,需配合 beta 请求头 message-threads-2026-08-12 使用。

Claude API message threads 是如何工作的?

在此之前,与 Messages API 对话的每一轮都要重新发送完整历史:系统提示词、工具和所有消息。根据 message threads 文档,API 每次都必须重新验证并重新分词全部内容。有了线程(thread),这部分工作大多只涉及新的一轮。

整个机制只是一个新参数 thread:

1. 第一个请求照常发送,包含完整对话、system 和 tools,外加 "thread": {"type": "create"}。API 会把对话连同 Claude 的回复一起保存在该回复的 id 下。
2. 后续请求带上 "thread": {"type": "continue", "previous_message_id": "<id>"},并且只包含新消息,例如用户的下一条消息或工具结果(tool_result)。
3. 省略 system 和 tools,因为线程会记住它们。在 continue 请求中发送它们会返回 400 错误。

据 Anthropic 介绍,这样请求更小,首个 token 的延迟更短、更稳定,即使对话越来越长也是如此。受益最大的是长时间运行的智能体循环:智能体要进行几十次工具调用,过去每次都得发送不断变长的历史(关于这类循环如何运作,详见什么是 AI 智能体一文)。

SDK 帮我们做了什么?

SDK 新增了辅助方法 client.beta.messages.thread(...)。用与普通请求相同的字段创建它,然后通过 thread.send(...) 发送后续每一轮。辅助方法会自动添加 beta 请求头,在第一轮创建线程,并在之后的轮次中继续它。

值得注意的是,SDK 中的测试版 tool runner 默认使用线程,因此基于它构建的智能体无需改代码就可能变快 (创建 runner 时可以关闭)。

辅助方法还会处理故障情况:线程过期时,它会在新的 create 请求中重新发送整个对话。不过,这份完整副本只保存在内存中,仅在辅助对象存在期间有效。

需要注意什么?

第一,生命周期很短。线程在最后一次请求后 5 分钟过期,API 最迟在最后一次使用后一小时内将其删除。文档称线程是 “best-effort”:应用程序必须始终是对话的权威数据来源,并且从一开始就要处理在收到 404 错误 thread_not_found 后重新发送全部内容的情况。

第二,哪些不能改。model、thinking、tool_choice、context_management 等字段在整个线程中必须保持相同的值,否则 API 会返回 thread_fingerprint_mismatch 错误。线程只能延长,每个回复 id 只能被继续一次。要编辑之前的消息或修改系统提示词,需要新建线程。

第三,提示词缓存(prompt caching)。线程本身不缓存任何内容。缓存照旧工作,带 thread 的请求最多只能有 4 个 cache_control 断点。最简单的做法是每一轮都在请求顶层发送相同的 cache_control。

第四,线程不支持的功能:

1. Message Batches 和 Token Counting。
2. Compaction(包括按需压缩)以及 context editing(文档中说明了一个例外)。
3. 启用了 HIPAA readiness 或 Inference hooks 的组织。

第五,数据。线程不符合 ZDR(零数据保留)条件。根据文档,对话、系统提示词和工具保存在内存中,使用服务器管理的密钥加密,绝不会写入持久化磁盘。

在哪里可用,支持哪些模型?

Message threads 目前以测试版形式提供于 Claude API、Claude Platform on AWS、Claude Models on Google Cloud(由 Anthropic 管理)和 Microsoft Foundry。支持的模型包括 Claude Fable 5.1 和 Mythos 5.1、Opus 5.5、Sonnet 5.5 和 Haiku 5.5,旧模型中也包括 Opus 4.5、Sonnet 4.5 和 Haiku 4.5。

线程不改变价格,也不改变速率限制。token 照常计费,所以节省的是时间和请求大小,成本仍然值得跟踪,例如通过新的 Claude 成本分析 API。这是近几天 API 本身的又一项变化,此前请求大小上限已提高到 128 MB。

(不要把它和 Claude Managed Agents 中的 “session threads” 混为一谈。正如文档提醒的,那是另一项功能。)

常见问题

什么是 Claude API message threads?

这是一项测试版功能,API 会在服务器端短时间保存对话。第一个请求之后,只需发送新消息和上一条回复的 id。

Message threads 能降低 Claude API 的成本吗?

不能直接降低。根据文档,线程不改变价格,也不改变速率限制。好处是请求更小,首个 token 的延迟更短。

Claude API 会保存线程多久?

线程在最后一次请求后 5 分钟过期,API 最迟在最后一次使用后一小时内将其删除。之后必须重新发送整个对话。

Message threads 能在 Amazon Bedrock 上使用吗?

文档列出的是 Claude API、Claude Platform on AWS、Claude Models on Google Cloud(由 Anthropic 管理)和 Microsoft Foundry。Amazon Bedrock 不在列表中。