Implementation:Anthropics Anthropic sdk python BetaContentBlock

Knowledge Sources	Anthropic SDK Python
Domains	API_Types, Beta_Features
Last Updated	2026-02-15 12:00 GMT

Overview

BetaContentBlock is a central union type alias that represents all possible content block types that can appear in a beta API response message. It is a discriminated union, using the type field to distinguish between 15 different content block variants.

Description

BetaContentBlock is defined as a TypeAlias using typing.Union wrapped in Annotated with a PropertyInfo(discriminator="type") annotation. This discriminated union pattern allows the SDK to automatically deserialize JSON response content blocks into the correct Python type based on the type field value.

The union includes the following block types:

BetaTextBlock -- Standard text content
BetaThinkingBlock -- Model thinking/reasoning content
BetaRedactedThinkingBlock -- Redacted thinking content
BetaToolUseBlock -- Tool invocation by the model
BetaServerToolUseBlock -- Server-side tool use
BetaWebSearchToolResultBlock -- Web search results
BetaWebFetchToolResultBlock -- Web fetch results
BetaCodeExecutionToolResultBlock -- Code execution results
BetaBashCodeExecutionToolResultBlock -- Bash code execution results
BetaTextEditorCodeExecutionToolResultBlock -- Text editor code execution results
BetaToolSearchToolResultBlock -- Tool search results
BetaMCPToolUseBlock -- MCP tool use
BetaMCPToolResultBlock -- MCP tool result
BetaContainerUploadBlock -- Container file upload
BetaCompactionBlock -- Compaction block

Usage

Use BetaContentBlock as a type annotation when you need to accept or process any content block from a beta API response. It is the type used for individual elements in the BetaMessage.content list. You typically interact with it via type narrowing (checking block.type) to handle each variant appropriately.

Code Reference

Source Location

Repository: Anthropic SDK Python
File: src/anthropic/types/beta/beta_content_block.py

Signature

BetaContentBlock: TypeAlias = Annotated[
    Union[
        BetaTextBlock,
        BetaThinkingBlock,
        BetaRedactedThinkingBlock,
        BetaToolUseBlock,
        BetaServerToolUseBlock,
        BetaWebSearchToolResultBlock,
        BetaWebFetchToolResultBlock,
        BetaCodeExecutionToolResultBlock,
        BetaBashCodeExecutionToolResultBlock,
        BetaTextEditorCodeExecutionToolResultBlock,
        BetaToolSearchToolResultBlock,
        BetaMCPToolUseBlock,
        BetaMCPToolResultBlock,
        BetaContainerUploadBlock,
        BetaCompactionBlock,
    ],
    PropertyInfo(discriminator="type"),
]

Import

from anthropic.types.beta import BetaContentBlock

I/O Contract

BetaContentBlock is a pure type alias and does not have input parameters. It describes the shape of data returned from the API.

Discriminator Field	Type	Description
`type`	`str`	Determines which concrete block type is represented

Variant Type	`type` Value	Description
`BetaTextBlock`	`"text"`	Plain text content from the model
`BetaThinkingBlock`	`"thinking"`	Model reasoning/thinking content
`BetaRedactedThinkingBlock`	`"redacted_thinking"`	Redacted thinking content
`BetaToolUseBlock`	`"tool_use"`	Tool invocation block
`BetaServerToolUseBlock`	`"server_tool_use"`	Server-side tool use
`BetaWebSearchToolResultBlock`	`"web_search_tool_result"`	Web search tool results
`BetaWebFetchToolResultBlock`	`"web_fetch_tool_result"`	Web fetch tool results
`BetaCodeExecutionToolResultBlock`	`"code_execution_tool_result"`	Code execution results
`BetaBashCodeExecutionToolResultBlock`	`"bash_code_execution_tool_result"`	Bash code execution results
`BetaTextEditorCodeExecutionToolResultBlock`	`"text_editor_code_execution_tool_result"`	Text editor execution results
`BetaToolSearchToolResultBlock`	`"tool_search_tool_result"`	Tool search results
`BetaMCPToolUseBlock`	`"mcp_tool_use"`	MCP protocol tool use
`BetaMCPToolResultBlock`	`"mcp_tool_result"`	MCP protocol tool result
`BetaContainerUploadBlock`	`"container_upload"`	Container file upload
`BetaCompactionBlock`	`"compaction"`	Compaction block

Usage Examples

Iterating Over Content Blocks

from anthropic.types.beta import BetaContentBlock, BetaMessage

def process_message(message: BetaMessage) -> None:
    for block in message.content:
        if block.type == "text":
            print(f"Text: {block.text}")
        elif block.type == "tool_use":
            print(f"Tool call: {block.name}({block.input})")
        elif block.type == "thinking":
            print(f"Thinking: {block.thinking}")

Type Narrowing with isinstance

from anthropic.types.beta import BetaContentBlock, BetaTextBlock, BetaToolUseBlock

def extract_text(block: BetaContentBlock) -> str | None:
    if isinstance(block, BetaTextBlock):
        return block.text
    return None

Related Pages

Anthropics_Anthropic_sdk_python_BetaContentBlockParam -- The input parameter counterpart of this union type
Anthropics_Anthropic_sdk_python_BetaMessage -- Uses BetaContentBlock in its content field
Anthropics_Anthropic_sdk_python_BetaRawContentBlockStartEvent -- Uses a similar union for streaming events
Anthropics_Anthropic_sdk_python_Message_Response -- Stable counterpart for non-beta message responses

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment