Anthropic SDK v2.2.0 发布：消息线程与成本报告新特性

Anthropic SDK v2.2.0 更新概览

据 GitHub 发布页面显示，Anthropic 官方 SDK 于 10 月 23 日推出 v2.2.0 版本。这次更新在 API 层面引入了消息线程支持，并对用量与成本报告功能进行了重构，同时修复了工具运行器和客户端中的多处边界问题。

作为开发者日常依赖的接口层，SDK 的小版本迭代往往直接影响集成体验。v2.2.0 虽然版本号变化不大，但涉及的消息线程与工具运行器回调行为，值得正在使用该 SDK 构建应用的团队关注。

API 层：消息线程与成本报告

消息线程支持

本次更新最显眼的功能是 API 新增对 message threads（消息线程）的支持。这意味着开发者可以在 SDK 中直接组织多轮对话的线程结构，而不必完全依赖手动拼接消息数组。对于需要维护长对话上下文的 Agent 类应用，这一能力可以减少状态管理上的样板代码。

官方发布说明未给出线程的详细语义，但从命名看，它更可能是对现有消息列表的一层封装，而非全新的消息模型。实际接入时建议先在小规模场景验证线程的生命周期与分页行为。

消息线程（message threads）在多轮对话系统中通常指一组按顺序关联的消息集合，其结构可能包含父子关系或引用关系，用于支持分支对话、重试或编辑历史等场景。与简单的消息数组相比，线程模型往往需要额外的元数据（如线程 ID、父消息 ID、时间戳）来维护上下文一致性。在 Agent 应用中，线程还可用于区分同一用户的不同会话，或同一会话中的不同尝试。由于官方未给出详细语义，接入时需关注线程的创建、追加、分页与过期策略，以及线程 ID 在后续请求中的传递方式。

用量与成本报告按维度拆分

API 还新增了按维度（by dimension）查看 usage 和 cost 报告的能力，同时将旧版报告标记为 legacy。这一改动对需要做成本归因的团队很实用——可以按组织、工作空间等维度切分消耗，而不是只看总量。

配套的文档修复也印证了这一点：发布说明中提到修正了 usage and cost report 的示例以及 ending_at 相关文档，并澄清了速率限制中的模型列表会因组织和工作空间而异。

按维度查看 usage 和 cost 报告，通常意味着 API 支持通过查询参数指定分组维度（如 organization_id、workspace_id、model 等），返回按维度聚合的消耗数据，而非仅总量。这对成本归因、预算分配和多团队资源核算至关重要。旧版报告被标记为 legacy，意味着其字段或行为可能不再演进，新项目应优先使用新接口。同时，文档中澄清速率限制的模型列表因组织和工作空间而异，提示不同租户的配额策略可能不同，成本报告与速率限制需结合具体维度理解。

工具运行器：回调行为的精细调整

history 交给调用方管理

append_messages() 之后，工具运行器的 history 现在交由调用方管理，当前回复也不再进入 set_messages_params() 回调。这一变化意味着回调拿到的参数更“干净”，调用方需要自行承担历史维护责任，灵活性提高但心智负担略有增加。

工具运行器（tool runner）通常负责在消息循环中自动执行工具调用并将结果追加到历史。此前 history 可能由运行器内部维护，调用方通过回调间接影响；现在 history 交由调用方管理，意味着运行器不再自动持久化或修改历史状态，调用方需在每次回调后自行更新消息列表。这提高了灵活性（可自定义存储、裁剪或重试策略），但也要求调用方确保历史与运行器状态同步，否则可能出现上下文丢失或重复执行。升级后应重点测试多轮工具调用中 history 的传递与更新逻辑。

function tools 的保留与剔除

当 set_messages_params() 以 definitions 形式给出 tools 时，工具运行器会继续运行其 function tools；而一旦某个工具被从 tools 中移除，运行器就不再执行它。这实际上让回调具备了动态启用/禁用工具的能力。

同时，set_messages_params() 回调会再次以 definitions 形式拿到 tools，保持了参数形态的一致性。

function tools 指以函数定义（definitions）形式描述的可调用工具，通常包含名称、描述和参数 schema。工具运行器根据这些定义决定哪些工具可被模型调用并执行。当 set_messages_params() 回调以 definitions 形式提供 tools 时，运行器仅执行其中仍存在的 function tools；若某工具被移除，运行器不再执行它，即使模型在历史中曾调用过。这实现了动态工具启用/禁用，但需注意：移除工具后，历史中已有的工具调用结果仍保留，模型可能基于旧结果继续推理，调用方应评估是否需同步清理历史或提示模型。

上下文字段的保留

工具运行器在 set_messages_params() 未提供 betas、user_profile_id 和 workspace_id 时，会保留原有值而不是清空。这类“缺省即保留”的处理方式，避免了回调只修改部分字段时意外丢失配置。

客户端与依赖的细节修复

客户端方面，max_retries 错误信息不再建议 math.inf，这是一个小的措辞修正，但对排查重试配置问题的开发者来说更清晰。

依赖层面，dev lockfile 中的 certifi 版本被提升。文档方面还有两处澄清：插件内容的扫描与校验描述，以及插件 served_version_pinned 与 updated_at 字段的含义。

升级建议

对于已经使用工具运行器的项目，v2.2.0 的回调行为变化属于需要留意的兼容性调整——尤其是 history 归属和 tools 动态剔除这两点，建议在升级后回归测试多轮工具调用流程。若只是使用基础消息接口，本次升级的风险较低，可以按常规节奏跟进。

消息线程与按维度成本报告目前仅出现在发布说明中，具体用法仍需参考官方文档，本文不对其行为做超出说明的推断。