Skip to main content
Chat primitives: the Message and ToolMessage components. Defines Message, the [Component](../../core/base#class-component) subtype used to represent a single turn in a chat history with a role (user, assistant, system, or tool), text content, and optional images and documents attachments. Also provides ToolMessage (a Message subclass that carries the tool name and arguments) and the as_chat_history utility for converting a [Context](../../core/base#class-context) into a flat list of Message objects.

​
Functions

​
FUNC as_chat_history 

as_chat_history(ctx: Context) -> list[Message]
Returns a list of Messages corresponding to a Context. Args:
  • ctx: A linear [Context](../../core/base#class-context) whose entries are Message or [ModelOutputThunk](../../core/base#class-modeloutputthunk) objects with Message parsed representations.
Returns:
  • List of Message objects in conversation order.
Raises:
  • Exception: If the context history is non-linear and cannot be cast to a flat list.
  • AssertionError: If any entry in the context cannot be converted to a Message.

​
Classes

​
CLASS Message

A single Message in a Chat history. TODO: we may want to deprecate this Component entirely. The fact that some Component gets rendered as a chat message is Formatter miscellania. Args:
  • role: The role that this message came from (e.g., "user", "assistant").
  • content: The content of the message.
  • images: Optional images associated with the message.
  • documents: Optional documents associated with the message.
Attributes:
  • Role: Type alias for the allowed role literals: "system", "user", "assistant", or "tool".
Methods:

​
FUNC images 

images(self) -> None | list[str]
Returns the images associated with this message as list of base 64 strings.

​
FUNC parts 

parts(self) -> list[Component | CBlock]
Return the constituent parts of this message, including content, documents, and images. Returns:
  • list[Component | CBlock]: A list beginning with the content block,
  • followed by any attached documents and image blocks.

​
FUNC format_for_llm 

format_for_llm(self) -> TemplateRepresentation
Formats the content for a Language Model. Returns:
  • The formatted output suitable for language models.

​
CLASS ToolMessage

Adds the name field for function name. Args:
  • role: The role of this message; most backends use "tool".
  • content: The content of the message; should be a stringified version of tool_output.
  • tool_output: The output of the tool or function call.
  • name: The name of the tool or function that was called.
  • args: The arguments passed to the tool.
  • tool: The [ModelToolCall](../../core/base#class-modeltoolcall) representation.
Attributes:
  • arguments: The arguments that were passed to the tool; stored from the args constructor parameter.
Methods:

​
FUNC format_for_llm 

format_for_llm(self) -> TemplateRepresentation
Return the same representation as Message with a name field added to the args dict. Returns:
  • Template representation including the tool
  • name alongside the standard message fields.