Principle:Anthropics Anthropic sdk python Content Block Separation

Knowledge Sources	Anthropic Python SDK Anthropic Extended Thinking Docs
Domains	Extended_Thinking, LLM, Reasoning
Last Updated	2026-02-15 00:00 GMT

Overview

Content Block Separation is the principle of using a discriminated union pattern to represent heterogeneous content types within a single API response. In the Anthropic Python SDK, a message response contains a list of content blocks where each block is one of several distinct types -- thinking, text, redacted thinking, tool use, and others -- distinguished by a type field discriminator.

This principle is fundamental to extended thinking because it enables the clean separation of internal reasoning (thinking blocks) from visible output (text blocks), while also handling edge cases such as safety-filtered content (redacted thinking blocks).

Theory: Discriminated Union Pattern for Heterogeneous Content

Language model responses are inherently heterogeneous. A single response may contain:

• Internal reasoning traces (thinking)
• User-visible text answers (text)
• Tool invocation requests (tool use)
• Safety-filtered reasoning (redacted thinking)
• Web search results (web search tool results)

Rather than using a single flat structure with optional fields (which would be error-prone and ambiguous), the SDK uses a discriminated union pattern:

• Each content type is a separate class with its own specific fields
• All types share a common type field that acts as the discriminator
• A Union type alias combines all possible block types
• Runtime dispatch uses the type field to determine which class applies

This pattern provides:

• Type safety: Each block type has exactly the fields it needs, no more
• Exhaustive handling: Type checkers can verify that all block types are handled
• Self-documenting structure: The type field makes the block's purpose immediately clear
• Forward compatibility: New block types can be added to the union without breaking existing code

Separating Thinking from Text

The core separation in extended thinking is between ThinkingBlock and TextBlock:

ThinkingBlock

Represents the model's internal chain-of-thought reasoning. Key characteristics:

• Contains a thinking field with the full reasoning text
• Contains a signature field with a cryptographic signature for multi-turn verification
• Appears before text blocks in the response content list
• Is not intended for display to end users (though it can be shown for debugging or transparency)

TextBlock

Represents the model's visible response. Key characteristics:

• Contains a text field with the answer text
• May contain optional citations for source attribution
• Appears after thinking blocks in the response content list
• Is the primary content to display to end users

Handling Redacted Thinking Blocks

In certain cases, the model's thinking content may be filtered by Anthropic's safety systems. When this happens, the thinking block is replaced by a RedactedThinkingBlock:

• The original thinking text is not available -- it has been removed by safety filters
• Instead, the block contains an opaque data field with encrypted content
• The data field must be preserved exactly when passing content back for multi-turn conversations
• The redacted block serves as a placeholder that maintains conversation continuity while enforcing safety constraints

This design follows the principle of transparent opacity: the developer knows that thinking occurred and was filtered, but cannot access the filtered content. The opaque data ensures that the model can still reference its prior reasoning in subsequent turns.

The ContentBlock Union

The full content block union encompasses all possible block types:

ContentBlock = Union[
    TextBlock,
    ThinkingBlock,
    RedactedThinkingBlock,
    ToolUseBlock,
    ServerToolUseBlock,
    WebSearchToolResultBlock,
]

The union is annotated with a PropertyInfo(discriminator="type") annotation that enables efficient runtime deserialization -- the SDK reads the type field first, then deserializes into the correct class.

Design Principles

Single Responsibility

Each block type has a single, well-defined purpose. ThinkingBlock holds reasoning, TextBlock holds output, RedactedThinkingBlock holds filtered reasoning. There is no overlap or ambiguity.

Ordered Content

The content list follows a defined ordering: thinking blocks appear first, followed by text blocks. This ordering is a structural guarantee from the API that simplifies client processing.

Preservation Semantics

Both ThinkingBlock and RedactedThinkingBlock carry fields that must be preserved exactly when echoed back in multi-turn conversations. This preservation requirement is a key architectural constraint that enables the model to verify the integrity of its prior reasoning.

Related Pages

Implemented By

• Implementation:Anthropics_Anthropic_sdk_python_ThinkingBlock_Separation