0
# Messages and Media
1

2
Rich message system supporting text, images, audio, video, documents, and binary content. Includes comprehensive streaming support and delta updates for real-time interactions.
3

4
## Capabilities
5

6
### Message Structure
7

8
Core message types for agent-model communication.
9

10
```python { .api }
11
class ModelRequest:
12
    """
13
    Request message sent to a model.
14
    """
15
    parts: list[ModelRequestPart]
16
    kind: Literal['request']
17

18
class ModelResponse:
19
    """
20
    Response message received from a model.
21
    """
22
    parts: list[ModelResponsePart]
23
    timestamp: datetime
24
    kind: Literal['response']
25

26
ModelMessage = ModelRequest | ModelResponse
27

28
class ModelMessagesTypeAdapter:
29
    """
30
    Type adapter for serializing/deserializing model messages.
31
    """
32
    def validate_python(self, data: Any) -> list[ModelMessage]: ...
33
    def dump_python(self, messages: list[ModelMessage]) -> list[dict]: ...
34
```
35

36
### Request Message Parts
37

38
Parts that can be included in requests to models.
39

40
```python { .api }
41
class SystemPromptPart:
42
    """System prompt message part."""
43
    content: str
44
    kind: Literal['system-prompt']
45

46
class UserPromptPart:
47
    """User prompt message part."""
48
    content: str | list[UserContent]
49
    timestamp: datetime
50
    kind: Literal['user-prompt']
51

52
class ToolReturnPart:
53
    """Tool return message part."""
54
    tool_name: str
55
    content: Any
56
    tool_id: str | None
57
    timestamp: datetime
58
    kind: Literal['tool-return']
59

60
class BuiltinToolReturnPart:
61
    """Built-in tool return message part."""
62
    tool_name: str
63
    content: Any
64
    tool_id: str | None
65
    timestamp: datetime
66
    kind: Literal['builtin-tool-return']
67

68
class RetryPromptPart:
69
    """Retry prompt message part."""
70
    content: str
71
    tool_name: str | None
72
    tool_id: str | None
73
    timestamp: datetime
74
    kind: Literal['retry-prompt']
75

76
ModelRequestPart = (
77
    SystemPromptPart |
78
    UserPromptPart |
79
    ToolReturnPart |
80
    BuiltinToolReturnPart |
81
    RetryPromptPart
82
)
83
```
84

85
### Response Message Parts
86

87
Parts that can be included in responses from models.
88

89
```python { .api }
90
class TextPart:
91
    """Plain text response part."""
92
    content: str
93
    kind: Literal['text']
94

95
class ThinkingPart:
96
    """Thinking response part for reasoning models like o1."""
97
    content: str
98
    kind: Literal['thinking']
99

100
class ToolCallPart:
101
    """Tool call request part."""
102
    tool_name: str
103
    args: dict[str, Any]
104
    tool_id: str | None
105
    kind: Literal['tool-call']
106

107
class BuiltinToolCallPart:
108
    """Built-in tool call part."""
109
    tool_name: str
110
    args: dict[str, Any]
111
    tool_id: str | None
112
    kind: Literal['builtin-tool-call']
113

114
ModelResponsePart = (
115
    TextPart |
116
    ThinkingPart |
117
    ToolCallPart |
118
    BuiltinToolCallPart
119
)
120
```
121

122
### Media and File Types
123

124
Support for various media types and file content.
125

126
```python { .api }
127
class FileUrl:
128
    """Abstract base for URL-based files."""
129
    url: str
130

131
class ImageUrl(FileUrl):
132
    """Image file URL with format and media type."""
133
    def __init__(
134
        self,
135
        url: str,
136
        *,
137
        alt: str | None = None,
138
        media_type: ImageMediaType | None = None
139
    ):
140
        """
141
        Create image URL.
142
        
143
        Parameters:
144
        - url: URL to image file
145
        - alt: Alt text for accessibility
146
        - media_type: MIME type of image
147
        """
148

149
class AudioUrl(FileUrl):
150
    """Audio file URL with format and media type."""
151
    def __init__(
152
        self,
153
        url: str,
154
        *,
155
        media_type: AudioMediaType | None = None
156
    ):
157
        """
158
        Create audio URL.
159
        
160
        Parameters:
161
        - url: URL to audio file
162
        - media_type: MIME type of audio
163
        """
164

165
class VideoUrl(FileUrl):
166
    """Video file URL with format and media type."""
167
    def __init__(
168
        self,
169
        url: str,
170
        *,
171
        media_type: VideoMediaType | None = None
172
    ):
173
        """
174
        Create video URL.
175
        
176
        Parameters:
177
        - url: URL to video file
178
        - media_type: MIME type of video
179
        """
180

181
class DocumentUrl(FileUrl):
182
    """Document file URL with format."""
183
    def __init__(
184
        self,
185
        url: str,
186
        *,
187
        media_type: DocumentMediaType | None = None
188
    ):
189
        """
190
        Create document URL.
191
        
192
        Parameters:
193
        - url: URL to document file
194
        - media_type: MIME type of document
195
        """
196

197
class BinaryContent:
198
    """Binary file content with format and media type."""
199
    def __init__(
200
        self,
201
        data: bytes,
202
        media_type: str,
203
        *,
204
        filename: str | None = None
205
    ):
206
        """
207
        Create binary content.
208
        
209
        Parameters:
210
        - data: Binary file data
211
        - media_type: MIME type of content
212
        - filename: Optional filename
213
        """
214
```
215

216
### Media Type Definitions
217

218
Type definitions for supported media formats.
219

220
```python { .api }
221
AudioMediaType = Literal[
222
    'audio/mpeg',
223
    'audio/wav',
224
    'audio/ogg',
225
    'audio/mp4',
226
    'audio/webm',
227
    'audio/flac'
228
]
229

230
ImageMediaType = Literal[
231
    'image/jpeg',
232
    'image/png',
233
    'image/gif',
234
    'image/webp',
235
    'image/svg+xml',
236
    'image/bmp'
237
]
238

239
VideoMediaType = Literal[
240
    'video/mp4',
241
    'video/webm',
242
    'video/ogg',
243
    'video/avi',
244
    'video/mov',
245
    'video/wmv'
246
]
247

248
DocumentMediaType = Literal[
249
    'application/pdf',
250
    'text/plain',
251
    'text/html',
252
    'text/markdown',
253
    'application/msword',
254
    'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
255
]
256

257
AudioFormat = Literal['mp3', 'wav', 'ogg', 'mp4', 'webm', 'flac']
258
ImageFormat = Literal['jpeg', 'png', 'gif', 'webp', 'svg', 'bmp']
259
VideoFormat = Literal['mp4', 'webm', 'ogg', 'avi', 'mov', 'wmv']
260
DocumentFormat = Literal['pdf', 'txt', 'html', 'md', 'doc', 'docx']
261
```
262

263
### User Content Types
264

265
Types of content that can be included in user messages.
266

267
```python { .api }
268
UserContent = (
269
    str |
270
    ImageUrl |
271
    AudioUrl |
272
    VideoUrl |
273
    DocumentUrl |
274
    BinaryContent
275
)
276
```
277

278
### Tool Return Handling
279

280
Structured tool return objects for complex tool outputs.
281

282
```python { .api }
283
class ToolReturn:
284
    """
285
    Structured tool return with content.
286
    """
287
    def __init__(
288
        self,
289
        content: Any,
290
        *,
291
        metadata: dict[str, Any] | None = None
292
    ):
293
        """
294
        Create tool return.
295
        
296
        Parameters:
297
        - content: Return content from tool
298
        - metadata: Optional metadata about the return
299
        """
300
```
301

302
### Streaming Events
303

304
Event types for streaming responses and real-time updates.
305

306
```python { .api }
307
class PartStartEvent:
308
    """New part started event."""
309
    part: ModelResponsePart
310
    kind: Literal['part-start']
311

312
class PartDeltaEvent:
313
    """Part delta update event."""
314
    delta: ModelResponsePartDelta
315
    kind: Literal['part-delta']
316

317
class FinalResultEvent:
318
    """Final result ready event."""
319
    result: Any
320
    kind: Literal['final-result']
321

322
class FunctionToolCallEvent:
323
    """Function tool call event."""
324
    tool_name: str
325
    args: dict[str, Any]
326
    tool_id: str | None
327
    kind: Literal['function-tool-call']
328

329
class FunctionToolResultEvent:
330
    """Function tool result event."""
331
    tool_name: str
332
    result: Any
333
    tool_id: str | None
334
    kind: Literal['function-tool-result']
335

336
class BuiltinToolCallEvent:
337
    """Built-in tool call event."""
338
    tool_name: str
339
    args: dict[str, Any]
340
    tool_id: str | None
341
    kind: Literal['builtin-tool-call']
342

343
class BuiltinToolResultEvent:
344
    """Built-in tool result event."""
345
    tool_name: str
346
    result: Any
347
    tool_id: str | None
348
    kind: Literal['builtin-tool-result']
349

350
ModelResponseStreamEvent = (
351
    PartStartEvent |
352
    PartDeltaEvent
353
)
354

355
HandleResponseEvent = (
356
    FunctionToolCallEvent |
357
    FunctionToolResultEvent |
358
    BuiltinToolCallEvent |
359
    BuiltinToolResultEvent
360
)
361

362
AgentStreamEvent = (
363
    ModelResponseStreamEvent |
364
    HandleResponseEvent |
365
    FinalResultEvent
366
)
367
```
368

369
### Delta Types for Streaming
370

371
Delta update types for streaming responses.
372

373
```python { .api }
374
class TextPartDelta:
375
    """Text part delta update."""
376
    content: str
377
    kind: Literal['text']
378

379
class ThinkingPartDelta:
380
    """Thinking part delta update."""
381
    content: str
382
    kind: Literal['thinking']
383

384
class ToolCallPartDelta:
385
    """Tool call part delta update."""
386
    tool_name: str | None
387
    args: dict[str, Any] | None
388
    tool_id: str | None
389
    kind: Literal['tool-call']
390

391
ModelResponsePartDelta = (
392
    TextPartDelta |
393
    ThinkingPartDelta |
394
    ToolCallPartDelta
395
)
396
```
397

398
## Usage Examples
399

400
### Basic Text Messages
401

402
```python
403
from pydantic_ai import Agent
404

405
agent = Agent(model='gpt-4', system_prompt='You are helpful.')
406

407
# Simple text interaction
408
result = agent.run_sync('Hello, how are you?')
409
print(result.data)
410
```
411

412
### Images in Messages
413

414
```python
415
from pydantic_ai import Agent, ImageUrl
416

417
agent = Agent(
418
    model='gpt-4-vision-preview',
419
    system_prompt='You can analyze images.'
420
)
421

422
# Send image with message
423
image = ImageUrl('https://example.com/image.jpg', alt='A sample image')
424
result = agent.run_sync(['Describe this image:', image])
425
print(result.data)
426
```
427

428
### Multiple Media Types
429

430
```python
431
from pydantic_ai import Agent, ImageUrl, AudioUrl, DocumentUrl
432

433
agent = Agent(
434
    model='gpt-4-turbo',
435
    system_prompt='You can process multiple media types.'
436
)
437

438
# Mix of text and media
439
content = [
440
    'Please analyze these files:',
441
    ImageUrl('https://example.com/chart.png'),
442
    AudioUrl('https://example.com/recording.mp3'),
443
    DocumentUrl('https://example.com/report.pdf')
444
]
445

446
result = agent.run_sync(content)
447
```
448

449
### Binary Content
450

451
```python
452
from pydantic_ai import Agent, BinaryContent
453

454
agent = Agent(model='gpt-4-vision-preview')
455

456
# Load image file as binary
457
with open('image.jpg', 'rb') as f:
458
    image_data = f.read()
459

460
binary_image = BinaryContent(
461
    data=image_data,
462
    media_type='image/jpeg',
463
    filename='image.jpg'
464
)
465

466
result = agent.run_sync(['Analyze this image:', binary_image])
467
```
468

469
### Message History
470

471
```python
472
from pydantic_ai import Agent
473
from pydantic_ai.messages import ModelRequest, UserPromptPart
474

475
agent = Agent(model='gpt-4')
476

477
# Create message history
478
message_history = [
479
    ModelRequest([
480
        UserPromptPart('What is the capital of France?')
481
    ])
482
]
483

484
# Continue conversation with history
485
result = agent.run_sync(
486
    'What about Germany?',
487
    message_history=message_history
488
)
489
```
490

491
### Streaming with Events
492

493
```python
494
from pydantic_ai import Agent
495

496
agent = Agent(model='gpt-4')
497

498
async def stream_example():
499
    stream = await agent.run_stream('Tell me a story')
500
    
501
    async for event in stream:
502
        if event.kind == 'part-delta':
503
            print(event.delta.content, end='', flush=True)
504
        elif event.kind == 'final-result':
505
            print(f"\n\nFinal result: {event.result}")
506
            break
507

508
# Run streaming example
509
import asyncio
510
asyncio.run(stream_example())
511
```