strands.types.content

Content-related type definitions for the SDK.

This module defines the types used to represent messages, content blocks, and other content-related structures in the SDK. These types are modeled after the Bedrock API.

• Bedrock docs: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Types_Amazon_Bedrock_Runtime.html

GuardContentText

class GuardContentText(TypedDict)

Defined in: src/strands/types/content.py:19

Text content to be evaluated by guardrails.

Attributes:

• qualifiers - The qualifiers describing the text block.
• text - The input text details to be evaluated by the guardrail.

GuardContent

class GuardContent(TypedDict)

Defined in: src/strands/types/content.py:31

Content block to be evaluated by guardrails.

Attributes:

• text - Text within content block to be evaluated by the guardrail.

ReasoningTextBlock

class ReasoningTextBlock(TypedDict)

Defined in: src/strands/types/content.py:41

Contains the reasoning that the model used to return the output.

Attributes:

• signature - A token that verifies that the reasoning text was generated by the model.
• text - The reasoning that the model used to return the output.

ReasoningContentBlock

class ReasoningContentBlock(TypedDict)

Defined in: src/strands/types/content.py:53

Contains content regarding the reasoning that is carried out by the model.

Attributes:

• reasoningText - The reasoning that the model used to return the output.
• redactedContent - The content in the reasoning that was encrypted by the model provider for safety reasons.

CachePoint

class CachePoint(TypedDict)

Defined in: src/strands/types/content.py:65

A cache point configuration for optimizing conversation history.

Attributes:

• type - The type of cache point, typically “default”.
• ttl - Optional cache TTL duration (e.g. “5m”, “1h”). Supported by providers that accept Anthropic-compatible cache_control fields.

ContentBlock

class ContentBlock(TypedDict)

Defined in: src/strands/types/content.py:78

A block of content for a message that you pass to, or receive from, a model.

Attributes:

• cachePoint - A cache point configuration to optimize conversation history.
• document - A document to include in the message.
• guardContent - Contains the content to assess with the guardrail.
• image - Image to include in the message.
• reasoningContent - Contains content regarding the reasoning that is carried out by the model.
• text - Text to include in the message.
• toolResult - The result for a tool request that a model makes.
• toolUse - Information about a tool use request from a model.
• video - Video to include in the message.
• citationsContent - Contains the citations for a document.

SystemContentBlock

class SystemContentBlock(TypedDict)

Defined in: src/strands/types/content.py:106

Contains configurations for instructions to provide the model for how to handle input.

Attributes:

• cachePoint - A cache point configuration to optimize conversation history.
• text - A system prompt for the model.

SystemPrompt

System prompt as either a plain string or structured content blocks (e.g., with cache points).

split_system_prompt

def split_system_prompt(
    system_prompt: SystemPrompt
) -> tuple[str | None, list[SystemContentBlock] | None]

Defined in: src/strands/types/content.py:122

Split a unified system prompt into the two-field form needed by Model.stream().

The string representation is maintained for backwards compatibility with model providers that expect system_prompt: str. The content block representation supports advanced features like cache points.

Returns:

(system_prompt_str, system_prompt_content) where:

• If string input: (string, [{text: string}])
• If list with text elements: (concatenated_text, list)
• If list without text elements: (None, list)
• If None: (None, None)

DeltaContent

class DeltaContent(TypedDict)

Defined in: src/strands/types/content.py:146

A block of content in a streaming response.

Attributes:

• text - The content text.
• toolUse - Information about a tool that the model is requesting to use.

ContentBlockStartToolUse

class ContentBlockStartToolUse(TypedDict)

Defined in: src/strands/types/content.py:158

The start of a tool use block.

Attributes:

• name - The name of the tool that the model is requesting to use.
• toolUseId - The ID for the tool request.
• reasoningSignature - Token that ties the model’s reasoning to this tool call.

ContentBlockStart

class ContentBlockStart(TypedDict)

Defined in: src/strands/types/content.py:172

Content block start information.

Attributes:

• toolUse - Information about a tool that the model is requesting to use.

ContentBlockDelta

class ContentBlockDelta(TypedDict)

Defined in: src/strands/types/content.py:182

The content block delta event.

Attributes:

• contentBlockIndex - The block index for a content block delta event.
• delta - The delta for a content block delta event.

ContentBlockStop

class ContentBlockStop(TypedDict)

Defined in: src/strands/types/content.py:194

A content block stop event.

Attributes:

• contentBlockIndex - The index for a content block.

Role

Role of a message sender.

• “user”: Messages from the user to the assistant
• “assistant”: Messages from the assistant to the user

MessageMetadata

class MessageMetadata(TypedDict)

Defined in: src/strands/types/content.py:212

Optional metadata attached to a message.

Not sent to model providers — explicitly stripped before model calls. Persisted alongside the message in session storage.

Attributes:

• usage - Token usage information from the model response.
• metrics - Performance metrics from the model response.
• custom - Arbitrary user/framework metadata (e.g. compression provenance).

Message

class Message(TypedDict)

Defined in: src/strands/types/content.py:229

A message in a conversation with the agent.

Attributes:

• content - The message content.
• role - The role of the message sender.
• metadata - Optional metadata, stripped before model calls.

Messages

A list of messages representing a conversation.

get_message_metadata

def get_message_metadata(message: Message) -> MessageMetadata

Defined in: src/strands/types/content.py:247

Get metadata for a message, returning empty dict if not present.

Individual fields (usage, metrics, custom) may not be present. Use .get() to safely access them.