Skip to content

Message block

Classes:

Name Description
AnnotationBlock

Annotation content block for messages.
AnnotationRef

Reference to annotation metadata (e.g., citation, note).
AudioBlock

Audio content block for messages.
DataBlock

Data content block for messages.
DocumentBlock

Document content block for messages.
ErrorBlock

Error content block for messages.
ImageBlock

Image content block for messages.
MediaRef

Reference to media content (image/audio/video/document/data).
ReasoningBlock

Reasoning content block for messages.
RemoteToolCallBlock

Remote Tool call content block for messages.
TextBlock

Text content block for messages.
ToolCallBlock

Tool call content block for messages.
ToolResultBlock

Tool result content block for messages.
VideoBlock

Video content block for messages.

Attributes:

Name Type Description
ContentBlock

Attributes

ContentBlock module-attribute 

ContentBlock = Annotated[Union[TextBlock, ImageBlock, AudioBlock, VideoBlock, DocumentBlock, DataBlock, ToolCallBlock, RemoteToolCallBlock, ToolResultBlock, ReasoningBlock, AnnotationBlock, ErrorBlock], Field(discriminator='type')]

Classes

AnnotationBlock

Bases: BaseModel

Annotation content block for messages.

Attributes:

Name Type Description
type Literal['annotation']

Block type discriminator.
kind Literal['citation', 'note']

Kind of annotation.
refs list[AnnotationRef]

List of annotation references.
spans list[tuple[int, int]] | None

Spans covered by the annotation.
Source code in agentflow/state/message_block.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
class AnnotationBlock(BaseModel):
    """
    Annotation content block for messages.

    Attributes:
        type (Literal["annotation"]): Block type discriminator.
        kind (Literal["citation", "note"]): Kind of annotation.
        refs (list[AnnotationRef]): List of annotation references.
        spans (list[tuple[int, int]] | None): Spans covered by the annotation.
    """

    type: Literal["annotation"] = "annotation"
    kind: Literal["citation", "note"] = "citation"
    refs: list[AnnotationRef] = Field(default_factory=list)
    spans: list[tuple[int, int]] | None = None

Attributes

kind class-attribute instance-attribute 
kind = 'citation'
refs class-attribute instance-attribute 
refs = Field(default_factory=list)
spans class-attribute instance-attribute 
spans = None
type class-attribute instance-attribute 
type = 'annotation'

AnnotationRef

Bases: BaseModel

Reference to annotation metadata (e.g., citation, note).

Attributes:

Name Type Description
url str | None

URL to annotation source.
file_id str | None

Provider-managed file ID.
page int | None

Page number (if applicable).
index int | None

Index within the annotation source.
title str | None

Title of the annotation.
Source code in agentflow/state/message_block.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
class AnnotationRef(BaseModel):
    """
    Reference to annotation metadata (e.g., citation, note).

    Attributes:
        url (str | None): URL to annotation source.
        file_id (str | None): Provider-managed file ID.
        page (int | None): Page number (if applicable).
        index (int | None): Index within the annotation source.
        title (str | None): Title of the annotation.
    """

    url: str | None = None
    file_id: str | None = None
    page: int | None = None
    index: int | None = None
    title: str | None = None

Attributes

file_id class-attribute instance-attribute 
file_id = None
index class-attribute instance-attribute 
index = None
page class-attribute instance-attribute 
page = None
title class-attribute instance-attribute 
title = None
url class-attribute instance-attribute 
url = None

AudioBlock

Bases: BaseModel

Audio content block for messages.

Attributes:

Name Type Description
type Literal['audio']

Block type discriminator.
media MediaRef

Reference to audio media.
transcript str | None

Transcript of audio.
sample_rate int | None

Sample rate in Hz.
channels int | None

Number of audio channels.
Source code in agentflow/state/message_block.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
class AudioBlock(BaseModel):
    """
    Audio content block for messages.

    Attributes:
        type (Literal["audio"]): Block type discriminator.
        media (MediaRef): Reference to audio media.
        transcript (str | None): Transcript of audio.
        sample_rate (int | None): Sample rate in Hz.
        channels (int | None): Number of audio channels.
    """

    type: Literal["audio"] = "audio"
    media: MediaRef
    transcript: str | None = None
    sample_rate: int | None = None
    channels: int | None = None

Attributes

channels class-attribute instance-attribute 
channels = None
media instance-attribute 
media
sample_rate class-attribute instance-attribute 
sample_rate = None
transcript class-attribute instance-attribute 
transcript = None
type class-attribute instance-attribute 
type = 'audio'

DataBlock

Bases: BaseModel

Data content block for messages.

Attributes:

Name Type Description
type Literal['data']

Block type discriminator.
mime_type str

MIME type of the data.
data_base64 str | None

Base64-encoded data.
media MediaRef | None

Reference to associated media.
Source code in agentflow/state/message_block.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
class DataBlock(BaseModel):
    """
    Data content block for messages.

    Attributes:
        type (Literal["data"]): Block type discriminator.
        mime_type (str): MIME type of the data.
        data_base64 (str | None): Base64-encoded data.
        media (MediaRef | None): Reference to associated media.
    """

    type: Literal["data"] = "data"
    mime_type: str
    data_base64: str | None = None
    media: MediaRef | None = None

Attributes

data_base64 class-attribute instance-attribute 
data_base64 = None
media class-attribute instance-attribute 
media = None
mime_type instance-attribute 
mime_type
type class-attribute instance-attribute 
type = 'data'

DocumentBlock

Bases: BaseModel

Document content block for messages.

Attributes:

Name Type Description
type Literal['document']

Block type discriminator.
media MediaRef

Reference to document media.
pages list[int] | None

List of page numbers.
excerpt str | None

Excerpt from the document.
Source code in agentflow/state/message_block.py 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
class DocumentBlock(BaseModel):
    """
    Document content block for messages.

    Attributes:
        type (Literal["document"]): Block type discriminator.
        media (MediaRef): Reference to document media.
        pages (list[int] | None): List of page numbers.
        excerpt (str | None): Excerpt from the document.
    """

    type: Literal["document"] = "document"
    media: MediaRef
    pages: list[int] | None = None
    excerpt: str | None = None

Attributes

excerpt class-attribute instance-attribute 
excerpt = None
media instance-attribute 
media
pages class-attribute instance-attribute 
pages = None
type class-attribute instance-attribute 
type = 'document'

ErrorBlock

Bases: BaseModel

Error content block for messages.

Attributes:

Name Type Description
type Literal['error']

Block type discriminator.
message str

Error message.
code str | None

Error code.
data dict[str, Any] | None

Additional error data.
Source code in agentflow/state/message_block.py 
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
class ErrorBlock(BaseModel):
    """
    Error content block for messages.

    Attributes:
        type (Literal["error"]): Block type discriminator.
        message (str): Error message.
        code (str | None): Error code.
        data (dict[str, Any] | None): Additional error data.
    """

    type: Literal["error"] = "error"
    message: str
    code: str | None = None
    data: dict[str, Any] | None = None

Attributes

code class-attribute instance-attribute 
code = None
data class-attribute instance-attribute 
data = None
message instance-attribute 
message
type class-attribute instance-attribute 
type = 'error'

ImageBlock

Bases: BaseModel

Image content block for messages.

Attributes:

Name Type Description
type Literal['image']

Block type discriminator.
media MediaRef

Reference to image media.
alt_text str | None

Alternative text for accessibility.
bbox list[float] | None

Bounding box coordinates [x1, y1, x2, y2].
Source code in agentflow/state/message_block.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class ImageBlock(BaseModel):
    """
    Image content block for messages.

    Attributes:
        type (Literal["image"]): Block type discriminator.
        media (MediaRef): Reference to image media.
        alt_text (str | None): Alternative text for accessibility.
        bbox (list[float] | None): Bounding box coordinates [x1, y1, x2, y2].
    """

    type: Literal["image"] = "image"
    media: MediaRef
    alt_text: str | None = None
    bbox: list[float] | None = None  # [x1,y1,x2,y2] if applicable

Attributes

alt_text class-attribute instance-attribute 
alt_text = None
bbox class-attribute instance-attribute 
bbox = None
media instance-attribute 
media
type class-attribute instance-attribute 
type = 'image'

MediaRef

Bases: BaseModel

Reference to media content (image/audio/video/document/data).

Prefer referencing by URL or provider file_id over inlining base64 for large payloads.

Attributes:

Name Type Description
kind Literal['url', 'file_id', 'data']

Type of reference.
url str | None

URL to media content.
file_id str | None

Provider-managed file ID.
data_base64 str | None

Base64-encoded data (small payloads only).
mime_type str | None

MIME type of the media.
size_bytes int | None

Size in bytes.
sha256 str | None

SHA256 hash of the media.
filename str | None

Filename of the media.
width int | None

Image width (if applicable).
height int | None

Image height (if applicable).
duration_ms int | None

Duration in milliseconds (if applicable).
page int | None

Page number (if applicable).
Source code in agentflow/state/message_block.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
class MediaRef(BaseModel):
    """
    Reference to media content (image/audio/video/document/data).

    Prefer referencing by URL or provider file_id over inlining base64 for large payloads.

    Attributes:
        kind (Literal["url", "file_id", "data"]): Type of reference.
        url (str | None): URL to media content.
        file_id (str | None): Provider-managed file ID.
        data_base64 (str | None): Base64-encoded data (small payloads only).
        mime_type (str | None): MIME type of the media.
        size_bytes (int | None): Size in bytes.
        sha256 (str | None): SHA256 hash of the media.
        filename (str | None): Filename of the media.
        width (int | None): Image width (if applicable).
        height (int | None): Image height (if applicable).
        duration_ms (int | None): Duration in milliseconds (if applicable).
        page (int | None): Page number (if applicable).
    """

    kind: Literal["url", "file_id", "data"] = "url"
    url: str | None = None  # http(s) or data: URL
    file_id: str | None = None  # provider-managed ID (e.g., OpenAI/Gemini)
    data_base64: str | None = None  # small payloads only
    mime_type: str | None = None
    size_bytes: int | None = None
    sha256: str | None = None
    filename: str | None = None
    # Media-specific hints
    width: int | None = None
    height: int | None = None
    duration_ms: int | None = None
    page: int | None = None

Attributes

data_base64 class-attribute instance-attribute 
data_base64 = None
duration_ms class-attribute instance-attribute 
duration_ms = None
file_id class-attribute instance-attribute 
file_id = None
filename class-attribute instance-attribute 
filename = None
height class-attribute instance-attribute 
height = None
kind class-attribute instance-attribute 
kind = 'url'
mime_type class-attribute instance-attribute 
mime_type = None
page class-attribute instance-attribute 
page = None
sha256 class-attribute instance-attribute 
sha256 = None
size_bytes class-attribute instance-attribute 
size_bytes = None
url class-attribute instance-attribute 
url = None
width class-attribute instance-attribute 
width = None

ReasoningBlock

Bases: BaseModel

Reasoning content block for messages.

Attributes:

Name Type Description
type Literal['reasoning']

Block type discriminator.
summary str

Summary of reasoning.
details list[str] | None

Detailed reasoning steps.
Source code in agentflow/state/message_block.py 
218
219
220
221
222
223
224
225
226
227
228
229
230
class ReasoningBlock(BaseModel):
    """
    Reasoning content block for messages.

    Attributes:
        type (Literal["reasoning"]): Block type discriminator.
        summary (str): Summary of reasoning.
        details (list[str] | None): Detailed reasoning steps.
    """

    type: Literal["reasoning"] = "reasoning"
    summary: str
    details: list[str] | None = None

Attributes

details class-attribute instance-attribute 
details = None
summary instance-attribute 
summary
type class-attribute instance-attribute 
type = 'reasoning'

RemoteToolCallBlock

Bases: BaseModel

Remote Tool call content block for messages.

Attributes:

Name Type Description
type Literal['remote_tool_call']

Block type discriminator.
id str

Tool call ID.
name str

Tool name.
args dict[str, Any]

Arguments for the tool call.
tool_type str | None

Type of tool (e.g., web_search, file_search).
Source code in agentflow/state/message_block.py 
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
class RemoteToolCallBlock(BaseModel):
    """
    Remote Tool call content block for messages.

    Attributes:
        type (Literal["remote_tool_call"]): Block type discriminator.
        id (str): Tool call ID.
        name (str): Tool name.
        args (dict[str, Any]): Arguments for the tool call.
        tool_type (str | None): Type of tool (e.g., web_search, file_search).
    """

    type: Literal["remote_tool_call"] = "remote_tool_call"
    id: str
    name: str
    args: dict[str, Any] = Field(default_factory=dict)
    tool_type: str = "remote"

Attributes

args class-attribute instance-attribute 
args = Field(default_factory=dict)
id instance-attribute 
id
name instance-attribute 
name
tool_type class-attribute instance-attribute 
tool_type = 'remote'
type class-attribute instance-attribute 
type = 'remote_tool_call'

TextBlock

Bases: BaseModel

Text content block for messages.

Attributes:

Name Type Description
type Literal['text']

Block type discriminator.
text str

Text content.
annotations list[AnnotationRef]

List of annotation references.
Source code in agentflow/state/message_block.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
class TextBlock(BaseModel):
    """
    Text content block for messages.

    Attributes:
        type (Literal["text"]): Block type discriminator.
        text (str): Text content.
        annotations (list[AnnotationRef]): List of annotation references.
    """

    type: Literal["text"] = "text"
    text: str
    annotations: list[AnnotationRef] = Field(default_factory=list)

Attributes

annotations class-attribute instance-attribute 
annotations = Field(default_factory=list)
text instance-attribute 
text
type class-attribute instance-attribute 
type = 'text'

ToolCallBlock

Bases: BaseModel

Tool call content block for messages.

Attributes:

Name Type Description
type Literal['tool_call']

Block type discriminator.
id str

Tool call ID.
name str

Tool name.
args dict[str, Any]

Arguments for the tool call.
tool_type str | None

Type of tool (e.g., web_search, file_search).
Source code in agentflow/state/message_block.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
class ToolCallBlock(BaseModel):
    """
    Tool call content block for messages.

    Attributes:
        type (Literal["tool_call"]): Block type discriminator.
        id (str): Tool call ID.
        name (str): Tool name.
        args (dict[str, Any]): Arguments for the tool call.
        tool_type (str | None): Type of tool (e.g., web_search, file_search).
    """

    type: Literal["tool_call"] = "tool_call"
    id: str
    name: str
    args: dict[str, Any] = Field(default_factory=dict)
    tool_type: str | None = None  # e.g., web_search, file_search, computer_use

Attributes

args class-attribute instance-attribute 
args = Field(default_factory=dict)
id instance-attribute 
id
name instance-attribute 
name
tool_type class-attribute instance-attribute 
tool_type = None
type class-attribute instance-attribute 
type = 'tool_call'

ToolResultBlock

Bases: BaseModel

Tool result content block for messages.

Attributes:

Name Type Description
type Literal['tool_result']

Block type discriminator.
call_id str

Tool call ID.
output Any

Output from the tool (str, dict, MediaRef, or list of blocks).
is_error bool

Whether the result is an error.
status Literal['completed', 'failed'] | None

Status of the tool call.
Source code in agentflow/state/message_block.py 
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
class ToolResultBlock(BaseModel):
    """
    Tool result content block for messages.

    Attributes:
        type (Literal["tool_result"]): Block type discriminator.
        call_id (str): Tool call ID.
        output (Any): Output from the tool (str, dict, MediaRef, or list of blocks).
        is_error (bool): Whether the result is an error.
        status (Literal["completed", "failed"] | None): Status of the tool call.
    """

    type: Literal["tool_result"] = "tool_result"
    call_id: str
    output: Any = None  # str | dict | MediaRef | list[ContentBlock-like]
    is_error: bool = False
    status: Literal["completed", "failed"] | None = None

Attributes

call_id instance-attribute 
call_id
is_error class-attribute instance-attribute 
is_error = False
output class-attribute instance-attribute 
output = None
status class-attribute instance-attribute 
status = None
type class-attribute instance-attribute 
type = 'tool_result'

VideoBlock

Bases: BaseModel

Video content block for messages.

Attributes:

Name Type Description
type Literal['video']

Block type discriminator.
media MediaRef

Reference to video media.
thumbnail MediaRef | None

Reference to thumbnail image.
Source code in agentflow/state/message_block.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
class VideoBlock(BaseModel):
    """
    Video content block for messages.

    Attributes:
        type (Literal["video"]): Block type discriminator.
        media (MediaRef): Reference to video media.
        thumbnail (MediaRef | None): Reference to thumbnail image.
    """

    type: Literal["video"] = "video"
    media: MediaRef
    thumbnail: MediaRef | None = None

Attributes

media instance-attribute 
media
thumbnail class-attribute instance-attribute 
thumbnail = None
type class-attribute instance-attribute 
type = 'video'