0
# Content Types and Chat History
1
2
Structured data types for representing messages, media content, function calls, conversation history, and real-time events. Provides a comprehensive type system for all forms of content that flow through Semantic Kernel.
3
4
## Capabilities
5
6
### Chat History and Messages
7
8
Core conversation management with support for multi-turn dialogs, role-based messaging, and conversation persistence.
9
10
```python { .api }
11
class ChatHistory:
12
"""
13
Container for managing conversation history and message sequences.
14
"""
15
16
def __init__(self, messages: list[ChatMessageContent] | None = None):
17
"""
18
Initialize ChatHistory with optional initial messages.
19
20
Parameters:
21
- messages: Initial list of ChatMessageContent messages
22
"""
23
24
def add_message(self, message: ChatMessageContent) -> None:
25
"""
26
Add a message to the chat history.
27
28
Parameters:
29
- message: ChatMessageContent to add to the history
30
"""
31
32
def add_user_message(self, content: str) -> None:
33
"""
34
Add a user message to the chat history.
35
36
Parameters:
37
- content: The user's message content
38
"""
39
40
def add_assistant_message(self, content: str) -> None:
41
"""
42
Add an assistant message to the chat history.
43
44
Parameters:
45
- content: The assistant's message content
46
"""
47
48
def add_system_message(self, content: str) -> None:
49
"""
50
Add a system message to the chat history.
51
52
Parameters:
53
- content: The system message content
54
"""
55
56
def remove_message(self, message: ChatMessageContent) -> bool:
57
"""
58
Remove a message from the chat history.
59
60
Parameters:
61
- message: The message to remove
62
63
Returns:
64
True if message was found and removed, False otherwise
65
"""
66
67
def clear(self) -> None:
68
"""Clear all messages from the chat history."""
69
70
@property
71
def messages(self) -> list[ChatMessageContent]:
72
"""Get all messages in the chat history."""
73
74
def __len__(self) -> int:
75
"""Get the number of messages in the history."""
76
77
def __iter__(self):
78
"""Iterate over messages in the history."""
79
80
class ChatMessageContent:
81
"""
82
Represents a single message in a conversation.
83
"""
84
85
def __init__(
86
self,
87
role: AuthorRole,
88
content: str | None = None,
89
name: str | None = None,
90
items: list[KernelContent] | None = None,
91
encoding: str | None = None,
92
ai_model_id: str | None = None,
93
metadata: dict[str, Any] | None = None,
94
inner_content: Any | None = None
95
):
96
"""
97
Initialize a chat message.
98
99
Parameters:
100
- role: The role of the message author (user, assistant, system, etc.)
101
- content: Text content of the message
102
- name: Optional name/identifier for the message author
103
- items: List of content items (text, images, function calls, etc.)
104
- encoding: Text encoding format
105
- ai_model_id: ID of the AI model that generated this message
106
- metadata: Additional metadata for the message
107
- inner_content: Raw content from the underlying AI service
108
"""
109
110
@property
111
def role(self) -> AuthorRole:
112
"""Get the message author role."""
113
114
@property
115
def content(self) -> str:
116
"""Get the text content of the message."""
117
118
@property
119
def name(self) -> str | None:
120
"""Get the message author name."""
121
122
@property
123
def items(self) -> list[KernelContent]:
124
"""Get the content items in this message."""
125
126
def __str__(self) -> str:
127
"""String representation of the message."""
128
129
class StreamingChatMessageContent:
130
"""
131
Represents a streaming chunk of a chat message.
132
"""
133
134
def __init__(
135
self,
136
role: AuthorRole | None = None,
137
content: str | None = None,
138
choice_index: int | None = None,
139
name: str | None = None,
140
ai_model_id: str | None = None,
141
metadata: dict[str, Any] | None = None,
142
inner_content: Any | None = None
143
):
144
"""
145
Initialize a streaming chat message chunk.
146
147
Parameters:
148
- role: The role of the message author
149
- content: Partial text content for this chunk
150
- choice_index: Index of this choice in multi-choice responses
151
- name: Optional name/identifier for the message author
152
- ai_model_id: ID of the AI model generating this content
153
- metadata: Additional metadata for the chunk
154
- inner_content: Raw content from the underlying AI service
155
"""
156
157
@property
158
def role(self) -> AuthorRole | None:
159
"""Get the message author role."""
160
161
@property
162
def content(self) -> str | None:
163
"""Get the partial text content."""
164
165
@property
166
def choice_index(self) -> int | None:
167
"""Get the choice index."""
168
```
169
170
### Content Item Types
171
172
Individual content items that can be included in messages.
173
174
```python { .api }
175
class TextContent:
176
"""
177
Represents text content within a message.
178
"""
179
180
def __init__(
181
self,
182
text: str,
183
ai_model_id: str | None = None,
184
metadata: dict[str, Any] | None = None,
185
inner_content: Any | None = None,
186
encoding: str | None = None
187
):
188
"""
189
Initialize text content.
190
191
Parameters:
192
- text: The text content
193
- ai_model_id: ID of the AI model that generated this content
194
- metadata: Additional metadata
195
- inner_content: Raw content from the underlying AI service
196
- encoding: Text encoding format
197
"""
198
199
@property
200
def text(self) -> str:
201
"""Get the text content."""
202
203
def __str__(self) -> str:
204
"""String representation of the text content."""
205
206
class StreamingTextContent:
207
"""
208
Represents streaming text content.
209
"""
210
211
def __init__(
212
self,
213
choice_index: int,
214
text: str | None = None,
215
ai_model_id: str | None = None,
216
metadata: dict[str, Any] | None = None,
217
inner_content: Any | None = None
218
):
219
"""
220
Initialize streaming text content.
221
222
Parameters:
223
- choice_index: Index of this choice in multi-choice responses
224
- text: Partial text content for this chunk
225
- ai_model_id: ID of the AI model generating this content
226
- metadata: Additional metadata
227
- inner_content: Raw content from the underlying AI service
228
"""
229
230
@property
231
def text(self) -> str | None:
232
"""Get the partial text content."""
233
234
@property
235
def choice_index(self) -> int:
236
"""Get the choice index."""
237
238
class ImageContent:
239
"""
240
Represents image content within a message.
241
"""
242
243
def __init__(
244
self,
245
uri: str | None = None,
246
data: bytes | None = None,
247
mime_type: str | None = None,
248
ai_model_id: str | None = None,
249
metadata: dict[str, Any] | None = None,
250
inner_content: Any | None = None
251
):
252
"""
253
Initialize image content.
254
255
Parameters:
256
- uri: URI/URL to the image
257
- data: Raw image data bytes
258
- mime_type: MIME type of the image (e.g., 'image/jpeg')
259
- ai_model_id: ID of the AI model that generated this content
260
- metadata: Additional metadata
261
- inner_content: Raw content from the underlying AI service
262
"""
263
264
@property
265
def uri(self) -> str | None:
266
"""Get the image URI."""
267
268
@property
269
def data(self) -> bytes | None:
270
"""Get the raw image data."""
271
272
@property
273
def mime_type(self) -> str | None:
274
"""Get the image MIME type."""
275
276
class AudioContent:
277
"""
278
Represents audio content within a message.
279
"""
280
281
def __init__(
282
self,
283
uri: str | None = None,
284
data: bytes | None = None,
285
mime_type: str | None = None,
286
ai_model_id: str | None = None,
287
metadata: dict[str, Any] | None = None,
288
inner_content: Any | None = None
289
):
290
"""
291
Initialize audio content.
292
293
Parameters:
294
- uri: URI/URL to the audio file
295
- data: Raw audio data bytes
296
- mime_type: MIME type of the audio (e.g., 'audio/wav')
297
- ai_model_id: ID of the AI model that generated this content
298
- metadata: Additional metadata
299
- inner_content: Raw content from the underlying AI service
300
"""
301
302
@property
303
def uri(self) -> str | None:
304
"""Get the audio URI."""
305
306
@property
307
def data(self) -> bytes | None:
308
"""Get the raw audio data."""
309
310
@property
311
def mime_type(self) -> str | None:
312
"""Get the audio MIME type."""
313
314
class FileReferenceContent:
315
"""
316
Represents a file reference within a message.
317
"""
318
319
def __init__(
320
self,
321
file_id: str,
322
ai_model_id: str | None = None,
323
metadata: dict[str, Any] | None = None,
324
inner_content: Any | None = None
325
):
326
"""
327
Initialize file reference content.
328
329
Parameters:
330
- file_id: Unique identifier for the referenced file
331
- ai_model_id: ID of the AI model that generated this content
332
- metadata: Additional metadata
333
- inner_content: Raw content from the underlying AI service
334
"""
335
336
@property
337
def file_id(self) -> str:
338
"""Get the file ID."""
339
340
class StreamingFileReferenceContent:
341
"""
342
Represents streaming file reference content.
343
"""
344
345
def __init__(
346
self,
347
choice_index: int,
348
file_id: str | None = None,
349
ai_model_id: str | None = None,
350
metadata: dict[str, Any] | None = None,
351
inner_content: Any | None = None
352
):
353
"""
354
Initialize streaming file reference content.
355
356
Parameters:
357
- choice_index: Index of this choice in multi-choice responses
358
- file_id: Unique identifier for the referenced file
359
- ai_model_id: ID of the AI model generating this content
360
- metadata: Additional metadata
361
- inner_content: Raw content from the underlying AI service
362
"""
363
364
@property
365
def file_id(self) -> str | None:
366
"""Get the file ID."""
367
368
@property
369
def choice_index(self) -> int:
370
"""Get the choice index."""
371
```
372
373
### Function Call Content
374
375
Content types for representing function calls and their results within conversations.
376
377
```python { .api }
378
class FunctionCallContent:
379
"""
380
Represents a function call within a message.
381
"""
382
383
def __init__(
384
self,
385
id: str,
386
name: str,
387
arguments: dict[str, Any] | None = None,
388
ai_model_id: str | None = None,
389
metadata: dict[str, Any] | None = None,
390
inner_content: Any | None = None
391
):
392
"""
393
Initialize function call content.
394
395
Parameters:
396
- id: Unique identifier for this function call
397
- name: Name of the function to call
398
- arguments: Arguments to pass to the function
399
- ai_model_id: ID of the AI model that generated this call
400
- metadata: Additional metadata
401
- inner_content: Raw content from the underlying AI service
402
"""
403
404
@property
405
def id(self) -> str:
406
"""Get the function call ID."""
407
408
@property
409
def name(self) -> str:
410
"""Get the function name."""
411
412
@property
413
def arguments(self) -> dict[str, Any]:
414
"""Get the function arguments."""
415
416
class FunctionResultContent:
417
"""
418
Represents the result of a function call within a message.
419
"""
420
421
def __init__(
422
self,
423
call_id: str,
424
name: str,
425
result: Any | None = None,
426
ai_model_id: str | None = None,
427
metadata: dict[str, Any] | None = None,
428
inner_content: Any | None = None
429
):
430
"""
431
Initialize function result content.
432
433
Parameters:
434
- call_id: ID of the function call this result corresponds to
435
- name: Name of the function that was called
436
- result: The result value from the function execution
437
- ai_model_id: ID of the AI model involved in this call
438
- metadata: Additional metadata
439
- inner_content: Raw content from the underlying AI service
440
"""
441
442
@property
443
def call_id(self) -> str:
444
"""Get the function call ID."""
445
446
@property
447
def name(self) -> str:
448
"""Get the function name."""
449
450
@property
451
def result(self) -> Any:
452
"""Get the function result."""
453
454
class AnnotationContent:
455
"""
456
Represents annotation content within a message.
457
"""
458
459
def __init__(
460
self,
461
file_id: str,
462
quote: str | None = None,
463
start_index: int | None = None,
464
end_index: int | None = None,
465
ai_model_id: str | None = None,
466
metadata: dict[str, Any] | None = None,
467
inner_content: Any | None = None
468
):
469
"""
470
Initialize annotation content.
471
472
Parameters:
473
- file_id: ID of the file being annotated
474
- quote: Quoted text from the file
475
- start_index: Start index of the annotation in the file
476
- end_index: End index of the annotation in the file
477
- ai_model_id: ID of the AI model that generated this annotation
478
- metadata: Additional metadata
479
- inner_content: Raw content from the underlying AI service
480
"""
481
482
@property
483
def file_id(self) -> str:
484
"""Get the file ID."""
485
486
@property
487
def quote(self) -> str | None:
488
"""Get the quoted text."""
489
490
class StreamingAnnotationContent:
491
"""
492
Represents streaming annotation content.
493
"""
494
495
def __init__(
496
self,
497
choice_index: int,
498
file_id: str | None = None,
499
quote: str | None = None,
500
start_index: int | None = None,
501
end_index: int | None = None,
502
ai_model_id: str | None = None,
503
metadata: dict[str, Any] | None = None,
504
inner_content: Any | None = None
505
):
506
"""
507
Initialize streaming annotation content.
508
509
Parameters:
510
- choice_index: Index of this choice in multi-choice responses
511
- file_id: ID of the file being annotated
512
- quote: Quoted text from the file
513
- start_index: Start index of the annotation in the file
514
- end_index: End index of the annotation in the file
515
- ai_model_id: ID of the AI model generating this content
516
- metadata: Additional metadata
517
- inner_content: Raw content from the underlying AI service
518
"""
519
520
@property
521
def choice_index(self) -> int:
522
"""Get the choice index."""
523
524
@property
525
def file_id(self) -> str | None:
526
"""Get the file ID."""
527
528
class ReasoningContent:
529
"""
530
Represents reasoning/thinking content within a message.
531
"""
532
533
def __init__(
534
self,
535
content: str,
536
ai_model_id: str | None = None,
537
metadata: dict[str, Any] | None = None,
538
inner_content: Any | None = None
539
):
540
"""
541
Initialize reasoning content.
542
543
Parameters:
544
- content: The reasoning or thinking text
545
- ai_model_id: ID of the AI model that generated this content
546
- metadata: Additional metadata
547
- inner_content: Raw content from the underlying AI service
548
"""
549
550
@property
551
def content(self) -> str:
552
"""Get the reasoning content."""
553
554
class StreamingReasoningContent:
555
"""
556
Represents streaming reasoning/thinking content.
557
"""
558
559
def __init__(
560
self,
561
choice_index: int,
562
content: str | None = None,
563
ai_model_id: str | None = None,
564
metadata: dict[str, Any] | None = None,
565
inner_content: Any | None = None
566
):
567
"""
568
Initialize streaming reasoning content.
569
570
Parameters:
571
- choice_index: Index of this choice in multi-choice responses
572
- content: Partial reasoning content for this chunk
573
- ai_model_id: ID of the AI model generating this content
574
- metadata: Additional metadata
575
- inner_content: Raw content from the underlying AI service
576
"""
577
578
@property
579
def choice_index(self) -> int:
580
"""Get the choice index."""
581
582
@property
583
def content(self) -> str | None:
584
"""Get the reasoning content."""
585
```
586
587
### Real-time Events
588
589
Event types for real-time communication scenarios.
590
591
```python { .api }
592
class RealtimeEvent:
593
"""
594
Base class for real-time events.
595
"""
596
597
def __init__(
598
self,
599
event_type: str,
600
ai_model_id: str | None = None,
601
metadata: dict[str, Any] | None = None
602
):
603
"""
604
Initialize a real-time event.
605
606
Parameters:
607
- event_type: Type of the real-time event
608
- ai_model_id: ID of the AI model associated with this event
609
- metadata: Additional metadata
610
"""
611
612
@property
613
def event_type(self) -> str:
614
"""Get the event type."""
615
616
class RealtimeTextEvent(RealtimeEvent):
617
"""
618
Real-time text event.
619
"""
620
621
def __init__(
622
self,
623
text: str,
624
ai_model_id: str | None = None,
625
metadata: dict[str, Any] | None = None
626
):
627
"""
628
Initialize a real-time text event.
629
630
Parameters:
631
- text: The text content
632
- ai_model_id: ID of the AI model associated with this event
633
- metadata: Additional metadata
634
"""
635
636
@property
637
def text(self) -> str:
638
"""Get the text content."""
639
640
class RealtimeAudioEvent(RealtimeEvent):
641
"""
642
Real-time audio event.
643
"""
644
645
def __init__(
646
self,
647
audio_data: bytes,
648
ai_model_id: str | None = None,
649
metadata: dict[str, Any] | None = None
650
):
651
"""
652
Initialize a real-time audio event.
653
654
Parameters:
655
- audio_data: Raw audio data
656
- ai_model_id: ID of the AI model associated with this event
657
- metadata: Additional metadata
658
"""
659
660
@property
661
def audio_data(self) -> bytes:
662
"""Get the audio data."""
663
664
class RealtimeFunctionCallEvent(RealtimeEvent):
665
"""
666
Real-time function call event.
667
"""
668
669
def __init__(
670
self,
671
call_id: str,
672
name: str,
673
arguments: dict[str, Any],
674
ai_model_id: str | None = None,
675
metadata: dict[str, Any] | None = None
676
):
677
"""
678
Initialize a real-time function call event.
679
680
Parameters:
681
- call_id: Unique identifier for the function call
682
- name: Name of the function to call
683
- arguments: Arguments to pass to the function
684
- ai_model_id: ID of the AI model associated with this event
685
- metadata: Additional metadata
686
"""
687
688
@property
689
def call_id(self) -> str:
690
"""Get the function call ID."""
691
692
@property
693
def name(self) -> str:
694
"""Get the function name."""
695
696
@property
697
def arguments(self) -> dict[str, Any]:
698
"""Get the function arguments."""
699
700
class RealtimeFunctionResultEvent(RealtimeEvent):
701
"""
702
Real-time function result event.
703
"""
704
705
def __init__(
706
self,
707
call_id: str,
708
result: Any,
709
ai_model_id: str | None = None,
710
metadata: dict[str, Any] | None = None
711
):
712
"""
713
Initialize a real-time function result event.
714
715
Parameters:
716
- call_id: ID of the function call this result corresponds to
717
- result: The result value from function execution
718
- ai_model_id: ID of the AI model associated with this event
719
- metadata: Additional metadata
720
"""
721
722
@property
723
def call_id(self) -> str:
724
"""Get the function call ID."""
725
726
@property
727
def result(self) -> Any:
728
"""Get the function result."""
729
730
class RealtimeImageEvent(RealtimeEvent):
731
"""
732
Real-time image event.
733
"""
734
735
def __init__(
736
self,
737
image_data: bytes,
738
mime_type: str = "image/jpeg",
739
ai_model_id: str | None = None,
740
metadata: dict[str, Any] | None = None
741
):
742
"""
743
Initialize a real-time image event.
744
745
Parameters:
746
- image_data: Raw image data
747
- mime_type: MIME type of the image
748
- ai_model_id: ID of the AI model associated with this event
749
- metadata: Additional metadata
750
"""
751
752
@property
753
def image_data(self) -> bytes:
754
"""Get the image data."""
755
756
@property
757
def mime_type(self) -> str:
758
"""Get the image MIME type."""
759
760
class RealtimeEvents:
761
"""
762
Container for managing real-time events.
763
"""
764
765
def __init__(self):
766
"""Initialize real-time events container."""
767
768
def add_event(self, event: RealtimeEvent) -> None:
769
"""
770
Add an event to the container.
771
772
Parameters:
773
- event: The real-time event to add
774
"""
775
776
def get_events(self, event_type: str | None = None) -> list[RealtimeEvent]:
777
"""
778
Get events from the container.
779
780
Parameters:
781
- event_type: Filter by event type (optional)
782
783
Returns:
784
List of matching real-time events
785
"""
786
```
787
788
### Content Utilities
789
790
Utility classes and enums for working with content.
791
792
```python { .api }
793
class AuthorRole:
794
"""
795
Enumeration of message author roles.
796
"""
797
USER: str = "user"
798
ASSISTANT: str = "assistant"
799
SYSTEM: str = "system"
800
TOOL: str = "tool"
801
802
class FinishReason:
803
"""
804
Enumeration of completion finish reasons.
805
"""
806
STOP: str = "stop"
807
LENGTH: str = "length"
808
FUNCTION_CALL: str = "function_call"
809
CONTENT_FILTER: str = "content_filter"
810
TOOL_CALLS: str = "tool_calls"
811
812
class ChatHistoryReducer:
813
"""
814
Base class for reducing chat history size.
815
"""
816
817
async def reduce(self, chat_history: ChatHistory) -> bool:
818
"""
819
Reduce the size of chat history.
820
821
Parameters:
822
- chat_history: The chat history to reduce
823
824
Returns:
825
True if reduction was performed, False otherwise
826
"""
827
828
class ChatHistoryTruncationReducer(ChatHistoryReducer):
829
"""
830
Reduces chat history by truncating old messages.
831
"""
832
833
def __init__(self, target_count: int):
834
"""
835
Initialize truncation reducer.
836
837
Parameters:
838
- target_count: Target number of messages to keep
839
"""
840
841
async def reduce(self, chat_history: ChatHistory) -> bool:
842
"""
843
Reduce chat history by removing oldest messages.
844
845
Parameters:
846
- chat_history: The chat history to reduce
847
848
Returns:
849
True if messages were removed, False otherwise
850
"""
851
852
class ChatHistorySummarizationReducer(ChatHistoryReducer):
853
"""
854
Reduces chat history by summarizing old messages.
855
"""
856
857
def __init__(
858
self,
859
target_count: int,
860
kernel: Kernel,
861
summarization_function: KernelFunction
862
):
863
"""
864
Initialize summarization reducer.
865
866
Parameters:
867
- target_count: Target number of messages to keep
868
- kernel: Kernel instance for summarization
869
- summarization_function: Function to use for summarization
870
"""
871
872
async def reduce(self, chat_history: ChatHistory) -> bool:
873
"""
874
Reduce chat history by summarizing older messages.
875
876
Parameters:
877
- chat_history: The chat history to reduce
878
879
Returns:
880
True if summarization was performed, False otherwise
881
"""
882
```
883
884
## Usage Examples
885
886
### Basic Chat History Management
887
888
```python
889
from semantic_kernel.contents import ChatHistory, ChatMessageContent, AuthorRole
890
891
# Create and manage chat history
892
chat_history = ChatHistory()
893
894
# Add messages
895
chat_history.add_user_message("Hello, how are you?")
896
chat_history.add_assistant_message("I'm doing well, thank you! How can I help you today?")
897
chat_history.add_user_message("Can you help me with Python programming?")
898
899
# Access messages
900
for message in chat_history:
901
print(f"{message.role}: {message.content}")
902
903
# Get message count
904
print(f"Total messages: {len(chat_history)}")
905
```
906
907
### Working with Multi-modal Content
908
909
```python
910
from semantic_kernel.contents import ChatMessageContent, TextContent, ImageContent, AuthorRole
911
912
# Create a message with mixed content
913
message = ChatMessageContent(
914
role=AuthorRole.USER,
915
items=[
916
TextContent("What's in this image?"),
917
ImageContent(uri="https://example.com/image.jpg")
918
]
919
)
920
921
# Access different content types
922
for item in message.items:
923
if isinstance(item, TextContent):
924
print(f"Text: {item.text}")
925
elif isinstance(item, ImageContent):
926
print(f"Image URI: {item.uri}")
927
```
928
929
### Function Call Integration
930
931
```python
932
from semantic_kernel.contents import FunctionCallContent, FunctionResultContent
933
934
# Create function call content
935
function_call = FunctionCallContent(
936
id="call_123",
937
name="get_weather",
938
arguments={"location": "Seattle", "units": "fahrenheit"}
939
)
940
941
# Create function result content
942
function_result = FunctionResultContent(
943
call_id="call_123",
944
name="get_weather",
945
result="The weather in Seattle is 72°F with partly cloudy skies"
946
)
947
948
# Add to chat history
949
chat_history.add_message(ChatMessageContent(
950
role=AuthorRole.ASSISTANT,
951
items=[function_call]
952
))
953
954
chat_history.add_message(ChatMessageContent(
955
role=AuthorRole.TOOL,
956
items=[function_result]
957
))
958
```