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”.

ContentBlock

class ContentBlock(TypedDict)

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

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:103

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.

DeltaContent

class DeltaContent(TypedDict)

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

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:127

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:141

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:151

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:163

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:181

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:198

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:216

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.