Share via

ChatHistory Class

This class holds the history of chat messages from a chat conversation.

Note: the system_message is added to the messages as a ChatMessageContent instance with role=AuthorRole.SYSTEM, but updating it will not update the messages list.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Constructor

ChatHistory(*, messages: list[ChatMessageContent] = None, system_message: str | None = None)

Parameters

Name Description
messages
Required

The messages to add to the chat history.
system_message
Required

A system message to add to the chat history, optional. if passed, it is added to the messages as a ChatMessageContent instance with role=AuthorRole.SYSTEM before any other messages.

Keyword-Only Parameters

Name Description
messages
Required
system_message
Required

Methods

add_assistant_message

Add an assistant message to the chat history.
add_developer_message

Add a system message to the chat history.
add_message

Add a message to the history.

This method accepts either a ChatMessageContent instance or a dictionary with the necessary information to construct a ChatMessageContent instance.
add_system_message

Add a system message to the chat history.
add_tool_message

Add a tool message to the chat history.
add_user_message

Add a user message to the chat history.
clear

Clear the chat history.
extend

Extend the chat history with a list of messages.
from_rendered_prompt

Create a ChatHistory instance from a rendered prompt.
load_chat_history_from_file

Loads the ChatHistory from a file.
remove_message

Remove a message from the history.
replace

Replace the chat history with a list of messages.

This calls clear() and then extend(messages=messages).
restore_chat_history

Restores a ChatHistory instance from a JSON string.
serialize

Serializes the ChatHistory instance to a JSON string.
store_chat_history_to_file

Stores the serialized ChatHistory to a file.
to_prompt

Return a string representation of the history.

add_assistant_message

Add an assistant message to the chat history.

add_assistant_message(content: str | list[KernelContent], **kwargs: Any) -> None

Parameters

Name Description
content
Required

The content of the assistant message, can be a string or a
ChatMessageContent.
Required
list of

ChatMessageContent. (list* of *<xref:KernelContent instances that are turned into a single>)
**kwargs
Required

Additional keyword arguments.

add_developer_message

Add a system message to the chat history.

add_developer_message(content: str | list[KernelContent], **kwargs) -> None

Parameters

Name Description
content
Required

The content of the developer message, can be a string or a
ChatMessageContent.
Required
list of

ChatMessageContent. (list* of *<xref:KernelContent instances that are turned into a single>)
**kwargs
Required

Additional keyword arguments.

add_message

Add a message to the history.

This method accepts either a ChatMessageContent instance or a dictionary with the necessary information to construct a ChatMessageContent instance.

add_message(message: ChatMessageContent | dict[str, Any], encoding: str | None = None, metadata: dict[str, Any] | None = None) -> None

Parameters

Name Description
message
Required
<xref:Union>[<xref:ChatMessageContent>,dict]

The message to add, either as a pre-constructed ChatMessageContent instance or a dictionary specifying 'role' and 'content'.
encoding
<xref:Optional>[str]

The encoding of the message. Required if 'message' is a dict.

Default value: None
metadata
<xref:Optional>[dict[str,<xref: Any>]]

Any metadata to attach to the message. Required if 'message' is a dict.

Default value: None

add_system_message

Add a system message to the chat history.

add_system_message(content: str | list[KernelContent], **kwargs) -> None

Parameters

Name Description
content
Required

The content of the system message, can be a string or a
ChatMessageContent.
Required
list of

ChatMessageContent. (list* of *<xref:KernelContent instances that are turned into a single>)
**kwargs
Required

Additional keyword arguments.

add_tool_message

Add a tool message to the chat history.

add_tool_message(content: str | list[KernelContent], **kwargs: Any) -> None

Parameters

Name Description
content
Required

The content of the tool message, can be a string or a
ChatMessageContent.
Required
list of

ChatMessageContent. (list* of *<xref:KernelContent instances that are turned into a single>)
**kwargs
Required

Additional keyword arguments.

add_user_message

Add a user message to the chat history.

add_user_message(content: str | list[KernelContent], **kwargs: Any) -> None

Parameters

Name Description
content
Required

The content of the user message, can be a string or a
ChatMessageContent.
Required
list of

ChatMessageContent. (list* of *<xref:KernelContent instances that are turned into a single>)
**kwargs
Required

Additional keyword arguments.

clear

Clear the chat history.

clear() -> None

extend

Extend the chat history with a list of messages.

extend(messages: Iterable[ChatMessageContent]) -> None

Parameters

Name Description
messages
Required

The messages to add to the history. Can be a list of ChatMessageContent instances or a ChatHistory itself.

from_rendered_prompt

Create a ChatHistory instance from a rendered prompt.

from_rendered_prompt(rendered_prompt: str) -> _T

Parameters

Name Description
rendered_prompt
Required
str

The rendered prompt to convert to a ChatHistory instance.

Returns

Type Description
ChatHistory

The ChatHistory instance created from the rendered prompt.

load_chat_history_from_file

Loads the ChatHistory from a file.

load_chat_history_from_file(file_path: str) -> ChatHistory

Parameters

Name Description
file_path
Required
str

The path to the file from which to load the ChatHistory.

Returns

Type Description
ChatHistory

The deserialized ChatHistory instance.

remove_message

Remove a message from the history.

remove_message(message: ChatMessageContent) -> bool

Parameters

Name Description
message
Required
<xref:semantic_kernel.contents.chat_history.ChatMessageContent>

The message to remove.

Returns

Type Description
bool

True if the message was removed, False if the message was not found.

replace

Replace the chat history with a list of messages.

This calls clear() and then extend(messages=messages).

replace(messages: Iterable[ChatMessageContent]) -> None

Parameters

Name Description
messages
Required

The messages to add to the history. Can be a list of ChatMessageContent instances or a ChatHistory itself.

restore_chat_history

Restores a ChatHistory instance from a JSON string.

restore_chat_history(chat_history_json: str) -> _T

Parameters

Name Description
chat_history_json
Required
str

The JSON string to deserialize into a ChatHistory instance.

Returns

Type Description
ChatHistory

The deserialized ChatHistory instance.

Exceptions

Type Description
ValueError

If the JSON string is invalid or the deserialized data fails validation.

serialize

Serializes the ChatHistory instance to a JSON string.

serialize() -> str

Returns

Type Description
str

A JSON string representation of the ChatHistory instance.

Exceptions

Type Description
ValueError

If the ChatHistory instance cannot be serialized to JSON.

store_chat_history_to_file

Stores the serialized ChatHistory to a file.

store_chat_history_to_file(file_path: str) -> None

Parameters

Name Description
file_path
Required
str

The path to the file where the serialized data will be stored.

to_prompt

Return a string representation of the history.

to_prompt() -> str

Attributes

messages 

messages: list[ChatMessageContent]

system_message 

system_message: str | None