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
Section titled “GuardContentText”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.
GuardContent
Section titled “GuardContent”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.
ReasoningTextBlock
Section titled “ReasoningTextBlock”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.
ReasoningContentBlock
Section titled “ReasoningContentBlock”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.
CachePoint
Section titled “CachePoint”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.
SummaryBlock
Section titled “SummaryBlock”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.
InjectedBlock
Section titled “InjectedBlock”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 aContextInjector’s name.
ContentBlock
Section titled “ContentBlock”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.
TextBlock
Section titled “TextBlock”@dataclassclass TextBlock()Defined in: src/strands/types/content.py:153
Text content for a message.
Attributes:
text- Text to send.
to_dict
Section titled “to_dict”def to_dict() -> _TextBlockDataDefined in: src/strands/types/content.py:162
Return the dictionary form of this block.
SystemContentBlock
Section titled “SystemContentBlock”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.
SystemPrompt
Section titled “SystemPrompt”System prompt as either a plain string or structured content blocks (e.g., with cache points).
split_system_prompt
Section titled “split_system_prompt”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)
DeltaContent
Section titled “DeltaContent”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.
ContentBlockStartToolUse
Section titled “ContentBlockStartToolUse”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.
ContentBlockStart
Section titled “ContentBlockStart”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.
ContentBlockDelta
Section titled “ContentBlockDelta”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.
ContentBlockStop
Section titled “ContentBlockStop”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
MessageMetadata
Section titled “MessageMetadata”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).
Message
Section titled “Message”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.
Messages
Section titled “Messages”A list of messages representing a conversation.
get_message_metadata
Section titled “get_message_metadata”def get_message_metadata(message: Message) -> MessageMetadataDefined 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.