Skip to content

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.

class GuardContentText(TypedDict)

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

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.
class GuardContent(TypedDict)

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

Content block to be evaluated by guardrails.

Attributes:

  • text - Text within content block to be evaluated by the guardrail.
class ReasoningTextBlock(TypedDict)

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

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.
class ReasoningContentBlock(TypedDict)

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

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.
class CachePoint(TypedDict)

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

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.
class SummaryBlock(TypedDict)

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

A summary of earlier conversation history that takes the summarized messages’ place.

Attributes:

  • provider - Name of the provider that wrote the summary server-side, for example “anthropic”.
  • signature - Signature the provider returned with the summary, sent back unchanged.
  • text - The summary text.
class InjectedBlock(TypedDict)

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

Text the app adds to a user turn, such as a reminder, kept apart from the user’s own words.

Readers of agent.messages can skip it ("injected" in block). ContextInjector writes its text as injected blocks. It belongs in a user message, after the existing content; in any other message it is left out.

When the model takes temporary messages (model_info.capabilities.temporary_messages), the provider sends it as a system message the model reads only until the next user message, which the model ranks above the user. Every other model receives only the latest user message’s injected text, as plain text. Keep content from outside the conversation, such as tool output or retrieved documents, out of it.

Attributes:

  • text - Text the app adds to the user turn.
  • source - Name of the component that added the text, such as a ContextInjector’s name.
class ContentBlock(TypedDict)

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

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

Attributes:

  • audio - Audio to include in the message.
  • 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.
  • injected - Text the app adds to a user turn, kept apart from the user’s own words.
  • reasoningContent - Contains content regarding the reasoning that is carried out by the model.
  • summary - A summary of earlier conversation history.
  • 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.
@dataclass
class TextBlock()

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

Text content for a message.

Attributes:

  • text - Text to send.
def to_dict() -> _TextBlockData

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

Return the dictionary form of this block.

class SystemContentBlock(TypedDict)

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

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.

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

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

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

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)
class DeltaContent(TypedDict)

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

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.
class ContentBlockStartToolUse(TypedDict)

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

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.
class ContentBlockStart(TypedDict)

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

Content block start information.

Attributes:

  • toolUse - Information about a tool that the model is requesting to use.
class ContentBlockDelta(TypedDict)

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

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.
class ContentBlockStop(TypedDict)

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

A content block stop event.

Attributes:

  • contentBlockIndex - The index for a content block.

Role of a message sender.

  • “user”: Messages from the user to the assistant
  • “assistant”: Messages from the assistant to the user
class MessageMetadata(TypedDict)

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

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).
class Message(TypedDict)

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

A message in a conversation with the agent.

Attributes:

  • content - The message content.
  • role - The role of the message sender.
  • tracking_id - Durable, stable UUID for the message. The agent assigns one automatically, so callers do not normally set it; a caller supplying its own should use a UUID v4 (str(uuid.uuid4())). Survives session save/restore and snapshots, and is stripped before model calls. Preserved when a message is copied or restored, so ids are unique within a conversation, but the same message carries the same id across sessions (copying another agent’s messages does not re-key them).
  • metadata - Optional metadata, stripped before model calls.

A list of messages representing a conversation.

def get_message_metadata(message: Message) -> MessageMetadata

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

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.