Anthropic SDK v2.2.0 Released: New Features for Message Threads and Cost Reports

Anthropic SDK v2.2.0 Update Overview

According to the GitHub release page, the official Anthropic SDK released version v2.2.0 on October 23. This update introduces message thread support at the API level, refactors the usage and cost reporting functionality, and fixes several edge cases in the tool runner and client.

As the interface layer that developers rely on daily, minor version iterations of the SDK often directly impact integration experience. Although the version number change in v2.2.0 is small, the changes involving message threads and tool runner callback behavior are worth the attention of teams currently building applications with this SDK.

API Layer: Message Threads and Cost Reports

Message Thread Support

The most prominent feature of this update is the API's new support for message threads. This means developers can directly organize the thread structure of multi-turn conversations within the SDK, rather than relying entirely on manually assembling message arrays. For Agent-type applications that need to maintain long conversation contexts, this capability can reduce boilerplate code for state management.

The official release notes do not provide detailed semantics for threads, but from the naming, it is more likely a wrapper around the existing message list rather than an entirely new message model. When integrating in practice, it is recommended to first validate the thread's lifecycle and pagination behavior in a small-scale scenario.

Message threads in multi-turn dialogue systems typically refer to a set of sequentially associated messages, whose structure may include parent-child or reference relationships, used to support scenarios such as branched conversations, retries, or edit history. Compared with a simple message array, the thread model often requires additional metadata (such as thread ID, parent message ID, timestamps) to maintain context consistency. In Agent applications, threads can also be used to distinguish different sessions of the same user, or different attempts within the same session. Since the official documentation does not provide detailed semantics, integration should focus on thread creation, appending, pagination, and expiration policies, as well as how the thread ID is passed in subsequent requests.

Usage and Cost Reports Split by Dimension

The API also adds the ability to view usage and cost reports by dimension, while marking the old reports as legacy. This change is very practical for teams that need cost attribution—consumption can be split by dimensions such as organization and workspace, rather than only viewing totals.

The accompanying documentation fixes confirm this: the release notes mention correcting the usage and cost report examples and the ending_at-related documentation, and clarifying that the model list in rate limits varies by organization and workspace.

Viewing usage and cost reports by dimension usually means the API supports specifying grouping dimensions via query parameters (such as organization_id, workspace_id, model, etc.), returning consumption data aggregated by dimension rather than only totals. This is crucial for cost attribution, budget allocation, and multi-team resource accounting. Old reports being marked as legacy means their fields or behavior may no longer evolve, and new projects should prioritize the new interface. At the same time, the documentation clarifies that the model list in rate limits varies by organization and workspace, suggesting that quota policies may differ across tenants, and cost reports and rate limits need to be understood in conjunction with specific dimensions.

Tool Runner: Fine-tuning of Callback Behavior

history Handed Over to the Caller

After append_messages(), the tool runner's history is now managed by the caller, and the current reply no longer enters the set_messages_params() callback. This change means the parameters received by the callback are "cleaner," and the caller needs to take on the responsibility of maintaining history themselves—flexibility increases, but the mental burden increases slightly.

The tool runner is typically responsible for automatically executing tool calls within the message loop and appending results to history. Previously, history may have been maintained internally by the runner, with the caller indirectly influencing it through callbacks; now history is managed by the caller, meaning the runner no longer automatically persists or modifies history state, and the caller must update the message list after each callback. This increases flexibility (custom storage, trimming, or retry policies can be implemented), but also requires the caller to ensure that history stays in sync with the runner state; otherwise, context loss or duplicate execution may occur. After upgrading, focus on testing the passing and updating logic of history in multi-turn tool calls.

Retention and Removal of function tools

When set_messages_params() provides tools in definitions form, the tool runner will continue to run its function tools; once a tool is removed from tools, the runner will no longer execute it. This effectively gives the callback the ability to dynamically enable/disable tools.

At the same time, the set_messages_params() callback will again receive tools in definitions form, maintaining consistency in parameter shape.

function tools refer to callable tools described in function definitions form, typically including name, description, and parameter schema. The tool runner decides which tools can be called and executed by the model based on these definitions. When the set_messages_params() callback provides tools in definitions form, the runner only executes the function tools still present among them; if a tool is removed, the runner will no longer execute it, even if the model has called it in history. This enables dynamic tool enabling/disabling, but note: after removing a tool, existing tool call results in history are still retained, and the model may continue reasoning based on old results; the caller should assess whether history needs to be cleaned up synchronously or the model needs to be prompted.

Retention of Context Fields

When set_messages_params() does not provide betas, user_profile_id, and workspace_id, the tool runner retains the original values instead of clearing them. This "retain when absent" approach avoids accidentally losing configuration when the callback only modifies some fields.

Minor Fixes in Client and Dependencies

On the client side, the max_retries error message no longer suggests math.inf. This is a small wording correction, but it is clearer for developers troubleshooting retry configuration issues.

At the dependency level, the certifi version in the dev lockfile has been bumped. There are also two clarifications in the documentation: the description of plugin content scanning and validation, and the meaning of the plugin served_version_pinned and updated_at fields.

Upgrade Recommendations

For projects already using the tool runner, the callback behavior changes in v2.2.0 are compatibility adjustments that require attention—especially the ownership of history and the dynamic removal of tools. It is recommended to regression-test multi-turn tool call flows after upgrading. If you are only using the basic message interface, the risk of this upgrade is low, and you can follow up at a regular pace.

Message threads and by-dimension cost reports currently only appear in the release notes; specific usage still needs to refer to the official documentation, and this article does not infer behavior beyond what is stated.

One-line Summary

Anthropic SDK v2.2.0 adds message threads and by-dimension cost reports, and adjusts tool runner callback behavior.

Paragraph Summary

The official Anthropic SDK released version v2.2.0 on October 23. The main updates include API-level support for message threads, making it easier to organize multi-turn conversation threads; usage and cost reports can now be viewed by dimension, with old reports marked as legacy. For the tool runner, history is now managed by the caller, the set_messages_params() callback no longer receives the current reply, and when tools are provided in definitions form, the runner only executes the function tools retained among them, enabling dynamic enable/disable. When the callback does not provide betas, user_profile_id, or workspace_id, the original values are retained. The client fixes the max_retries error message, and the documentation clarifies plugin and rate limit details. Upgrade recommendations: pay attention to tool runner callback compatibility; the risk for the basic message interface is low.