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 Required	<xref:Optional>[str] The encoding of the message. Required if 'message' is a dict. Default value: None
metadata Required	<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