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

Messages = List[Message] module-attribute

A list of messages representing a conversation.

Role = Literal['user', 'assistant'] module-attribute

Role of a message sender.

• "user": Messages from the user to the assistant
• "assistant": Messages from the assistant to the user

CachePoint

Bases: TypedDict

A cache point configuration for optimizing conversation history.

Attributes:

Name	Type	Description
type	str	The type of cache point, typically "default".

Source code in strands/types/content.py

class CachePoint(TypedDict):
    """A cache point configuration for optimizing conversation history.

    Attributes:
        type: The type of cache point, typically "default".
    """

    type: str

CitationsContentBlock

Bases: TypedDict

A content block containing generated text and associated citations.

This block type is returned when document citations are enabled, providing traceability between the generated content and the source documents that informed the response.

Attributes:

Name	Type	Description
citations	List[Citation]	An array of citations that reference the source documents used to generate the associated content.
content	List[CitationGeneratedContent]	The generated content that is supported by the associated citations.

Source code in strands/types/citations.py

class CitationsContentBlock(TypedDict, total=False):
    """A content block containing generated text and associated citations.

    This block type is returned when document citations are enabled, providing
    traceability between the generated content and the source documents that
    informed the response.

    Attributes:
        citations: An array of citations that reference the source documents
            used to generate the associated content.
        content: The generated content that is supported by the associated
            citations.
    """

    citations: List[Citation]
    content: List[CitationGeneratedContent]

ContentBlock

Bases: TypedDict

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

Attributes:

Name	Type	Description
cachePoint	CachePoint	A cache point configuration to optimize conversation history.
document	DocumentContent	A document to include in the message.
guardContent	GuardContent	Contains the content to assess with the guardrail.
image	ImageContent	Image to include in the message.
reasoningContent	ReasoningContentBlock	Contains content regarding the reasoning that is carried out by the model.
text	str	Text to include in the message.
toolResult	ToolResult	The result for a tool request that a model makes.
toolUse	ToolUse	Information about a tool use request from a model.
video	VideoContent	Video to include in the message.
citationsContent	CitationsContentBlock	Contains the citations for a document.

Source code in strands/types/content.py

class ContentBlock(TypedDict, total=False):
    """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.
    """

    cachePoint: CachePoint
    document: DocumentContent
    guardContent: GuardContent
    image: ImageContent
    reasoningContent: ReasoningContentBlock
    text: str
    toolResult: ToolResult
    toolUse: ToolUse
    video: VideoContent
    citationsContent: CitationsContentBlock

ContentBlockDelta

Bases: TypedDict

The content block delta event.

Attributes:

Name	Type	Description
contentBlockIndex	int	The block index for a content block delta event.
delta	DeltaContent	The delta for a content block delta event.

Source code in strands/types/content.py

class ContentBlockDelta(TypedDict):
    """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.
    """

    contentBlockIndex: int
    delta: DeltaContent

ContentBlockStart

Bases: TypedDict

Content block start information.

Attributes:

Name	Type	Description
toolUse	Optional[ContentBlockStartToolUse]	Information about a tool that the model is requesting to use.

Source code in strands/types/content.py

class ContentBlockStart(TypedDict, total=False):
    """Content block start information.

    Attributes:
        toolUse: Information about a tool that the model is requesting to use.
    """

    toolUse: Optional[ContentBlockStartToolUse]

ContentBlockStartToolUse

Bases: TypedDict

The start of a tool use block.

Attributes:

Name	Type	Description
name	str	The name of the tool that the model is requesting to use.
toolUseId	str	The ID for the tool request.

Source code in strands/types/content.py

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

    name: str
    toolUseId: str

ContentBlockStop

Bases: TypedDict

A content block stop event.

Attributes:

Name	Type	Description
contentBlockIndex	int	The index for a content block.

Source code in strands/types/content.py

class ContentBlockStop(TypedDict):
    """A content block stop event.

    Attributes:
        contentBlockIndex: The index for a content block.
    """

    contentBlockIndex: int

DeltaContent

Bases: TypedDict

A block of content in a streaming response.

Attributes:

Name	Type	Description
text	str	The content text.
toolUse	Dict[Literal['input'], str]	Information about a tool that the model is requesting to use.

Source code in strands/types/content.py

class DeltaContent(TypedDict, total=False):
    """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.
    """

    text: str
    toolUse: Dict[Literal["input"], str]

DocumentContent

Bases: TypedDict

A document to include in a message.

Attributes:

Name	Type	Description
format	Literal['pdf', 'csv', 'doc', 'docx', 'xls', 'xlsx', 'html', 'txt', 'md']	The format of the document (e.g., "pdf", "txt").
name	str	The name of the document.
source	DocumentSource	The source containing the document's binary content.

Source code in strands/types/media.py

class DocumentContent(TypedDict, total=False):
    """A document to include in a message.

    Attributes:
        format: The format of the document (e.g., "pdf", "txt").
        name: The name of the document.
        source: The source containing the document's binary content.
    """

    format: Literal["pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md"]
    name: str
    source: DocumentSource
    citations: Optional[CitationsConfig]
    context: Optional[str]

GuardContent

Bases: TypedDict

Content block to be evaluated by guardrails.

Attributes:

Name	Type	Description
text	GuardContentText	Text within content block to be evaluated by the guardrail.

Source code in strands/types/content.py

class GuardContent(TypedDict):
    """Content block to be evaluated by guardrails.

    Attributes:
        text: Text within content block to be evaluated by the guardrail.
    """

    text: GuardContentText

GuardContentText

Bases: TypedDict

Text content to be evaluated by guardrails.

Attributes:

Name	Type	Description
qualifiers	List[Literal['grounding_source', 'query', 'guard_content']]	The qualifiers describing the text block.
text	str	The input text details to be evaluated by the guardrail.

Source code in strands/types/content.py

class GuardContentText(TypedDict):
    """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.
    """

    qualifiers: List[Literal["grounding_source", "query", "guard_content"]]
    text: str

ImageContent

Bases: TypedDict

An image to include in a message.

Attributes:

Name	Type	Description
format	ImageFormat	The format of the image (e.g., "png", "jpeg").
source	ImageSource	The source containing the image's binary content.

Source code in strands/types/media.py

class ImageContent(TypedDict):
    """An image to include in a message.

    Attributes:
        format: The format of the image (e.g., "png", "jpeg").
        source: The source containing the image's binary content.
    """

    format: ImageFormat
    source: ImageSource

Message

Bases: TypedDict

A message in a conversation with the agent.

Attributes:

Name	Type	Description
content	List[ContentBlock]	The message content.
role	Role	The role of the message sender.

Source code in strands/types/content.py

class Message(TypedDict):
    """A message in a conversation with the agent.

    Attributes:
        content: The message content.
        role: The role of the message sender.
    """

    content: List[ContentBlock]
    role: Role

ReasoningContentBlock

Bases: TypedDict

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

Attributes:

Name	Type	Description
reasoningText	ReasoningTextBlock	The reasoning that the model used to return the output.
redactedContent	bytes	The content in the reasoning that was encrypted by the model provider for safety reasons.

Source code in strands/types/content.py

class ReasoningContentBlock(TypedDict, total=False):
    """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.
    """

    reasoningText: ReasoningTextBlock
    redactedContent: bytes

ReasoningTextBlock

Bases: TypedDict

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

Attributes:

Name	Type	Description
signature	Optional[str]	A token that verifies that the reasoning text was generated by the model.
text	str	The reasoning that the model used to return the output.

Source code in strands/types/content.py

class ReasoningTextBlock(TypedDict, total=False):
    """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.
    """

    signature: Optional[str]
    text: str

SystemContentBlock

Bases: TypedDict

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

Attributes:

Name	Type	Description
cachePoint	CachePoint	A cache point configuration to optimize conversation history.
text	str	A system prompt for the model.

Source code in strands/types/content.py

class SystemContentBlock(TypedDict, total=False):
    """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.
    """

    cachePoint: CachePoint
    text: str

ToolResult

Bases: TypedDict

Result of a tool execution.

Attributes:

Name	Type	Description
content	list[ToolResultContent]	List of result content returned by the tool.
status	ToolResultStatus	The status of the tool execution ("success" or "error").
toolUseId	str	The unique identifier of the tool use request that produced this result.

Source code in strands/types/tools.py

class ToolResult(TypedDict):
    """Result of a tool execution.

    Attributes:
        content: List of result content returned by the tool.
        status: The status of the tool execution ("success" or "error").
        toolUseId: The unique identifier of the tool use request that produced this result.
    """

    content: list[ToolResultContent]
    status: ToolResultStatus
    toolUseId: str

ToolUse

Bases: TypedDict

A request from the model to use a specific tool with the provided input.

Attributes:

Name	Type	Description
input	Any	The input parameters for the tool. Can be any JSON-serializable type.
name	str	The name of the tool to invoke.
toolUseId	str	A unique identifier for this specific tool use request.

Source code in strands/types/tools.py

class ToolUse(TypedDict):
    """A request from the model to use a specific tool with the provided input.

    Attributes:
        input: The input parameters for the tool.
            Can be any JSON-serializable type.
        name: The name of the tool to invoke.
        toolUseId: A unique identifier for this specific tool use request.
    """

    input: Any
    name: str
    toolUseId: str

VideoContent

Bases: TypedDict

A video to include in a message.

Attributes:

Name	Type	Description
format	VideoFormat	The format of the video (e.g., "mp4", "avi").
source	VideoSource	The source containing the video's binary content.

Source code in strands/types/media.py

class VideoContent(TypedDict):
    """A video to include in a message.

    Attributes:
        format: The format of the video (e.g., "mp4", "avi").
        source: The source containing the video's binary content.
    """

    format: VideoFormat
    source: VideoSource