Implementation:Anthropics Anthropic sdk python ParsedBetaMessage

Knowledge Sources	Anthropic SDK Python
Domains	API Types, Beta, Structured Output
Last Updated	2026-02-15 12:00 GMT

Overview

ParsedBetaMessage is a generic Pydantic model that extends BetaMessage with structured output parsing capabilities. It provides a typed parsed_output property that extracts and returns a deserialized response object from text content blocks, enabling type-safe access to structured API responses.

Description

The module defines three key types:

1. ParsedBetaTextBlock[ResponseFormatT] -- A generic extension of BetaTextBlock that adds an optional parsed_output field of type ResponseFormatT. This field is excluded from API serialization via __api_exclude__.

1. ParsedBetaContentBlock[ResponseFormatT] -- A discriminated union type alias that includes ParsedBetaTextBlock alongside all other beta content block types (thinking, redacted thinking, tool use, server tool use, web search results, code execution results, MCP tool use/results, container uploads, and compaction blocks). Discrimination is based on the type field.

1. ParsedBetaMessage[ResponseFormatT] -- A generic extension of BetaMessage that overrides the content field to use ParsedBetaContentBlock and provides a parsed_output property. This property iterates over content blocks and returns the parsed_output from the first text block that has one.

The generic type parameter ResponseFormatT defaults to None, making it usable without explicit parameterization.

Usage

Use ParsedBetaMessage when working with structured output responses from the beta API. It is typically returned by helper methods that parse Claude's text output into a specific Pydantic model or dataclass. This is useful for:

• Extracting typed, structured data from Claude's responses without manual JSON parsing.
• Working with beta features that produce structured outputs (e.g., JSON mode with schema enforcement).
• Type-safe access to parsed response data in IDE-assisted development.

Code Reference

Source Location

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

Signature

ResponseFormatT = TypeVar("ResponseFormatT", default=None)


class ParsedBetaTextBlock(BetaTextBlock, Generic[ResponseFormatT]):
    parsed_output: Optional[ResponseFormatT] = None
    __api_exclude__ = {"parsed_output"}


ParsedBetaContentBlock: TypeAlias = Annotated[
    Union[
        ParsedBetaTextBlock[ResponseFormatT],
        BetaThinkingBlock,
        BetaRedactedThinkingBlock,
        BetaToolUseBlock,
        BetaServerToolUseBlock,
        BetaWebSearchToolResultBlock,
        BetaCodeExecutionToolResultBlock,
        BetaBashCodeExecutionToolResultBlock,
        BetaTextEditorCodeExecutionToolResultBlock,
        BetaMCPToolUseBlock,
        BetaMCPToolResultBlock,
        BetaContainerUploadBlock,
        BetaCompactionBlock,
    ],
    PropertyInfo(discriminator="type"),
]


class ParsedBetaMessage(BetaMessage, Generic[ResponseFormatT]):
    content: List[ParsedBetaContentBlock[ResponseFormatT]]

    @property
    def parsed_output(self) -> Optional[ResponseFormatT]:
        for content in self.content:
            if content.type == "text" and content.parsed_output:
                return content.parsed_output
        return None

Import

from anthropic.types.beta import ParsedBetaMessage

I/O Contract

ParsedBetaMessage Fields (inherited from BetaMessage + extensions)

Field / Property	Type	Description
content	List[ParsedBetaContentBlock[ResponseFormatT]]	List of content blocks, where text blocks may include parsed output.
parsed_output (property)	Optional[ResponseFormatT]	Returns the parsed output from the first text block that has one, or None.

ParsedBetaTextBlock Fields (extends BetaTextBlock)

Field	Type	Description
parsed_output	Optional[ResponseFormatT]	The deserialized structured output. Excluded from API serialization.

Usage Examples

from pydantic import BaseModel
import anthropic

client = anthropic.Anthropic()


class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


# Using beta structured output parsing
message = client.beta.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Create a calendar event for a team meeting next Friday with Alice and Bob.",
        }
    ],
    betas=["structured-output-2025-01-01"],
)

# Access typed parsed output (when using parsing helpers)
# parsed: ParsedBetaMessage[CalendarEvent]
# event = parsed.parsed_output
# print(event.name, event.date, event.participants)

Related Pages

• BetaUsage -- Usage information included in the parent BetaMessage that ParsedBetaMessage extends.
• Beta MessageCountTokensParams -- Parameters for beta API requests that produce responses parseable into this type.