liveBook · Manning

ChatMessage

As explained in Build a Multi-Agent System (from Scratch)

ChatMessage is a structured representation of a message in an LLM conversation, including its role and content.

A ChatMessage represents one message in an LLM conversation. It records the message’s role and content and can carry tool-call requests, allowing a chat history to capture both ordinary dialogue and tool interactions. section 3.1.1 section 3.1

The Python implementation uses a Pydantic BaseModel with three fields: role is a ChatRole, content is a string, and tool_calls is an optional list of ToolCall objects. ChatRole is a string-valued enum with four roles. section 3.1.1

The roles identify each message’s purpose:

  • SYSTEM sets general context, such as the LLM’s role in the interaction. section 3.1.1
  • USER represents input from the user; in an agent interaction, it can represent input from the agent. section 3.1.1 section 4.2.3
  • ASSISTANT represents an LLM response and is the only role used to carry tool-call requests. section 3.1.1 section 3.1.2
  • TOOL carries a tool result back to the LLM. section 3.1.1
Listing 3.2 Implementing ChatMessage and ChatRole
# llm_agents_from_scratch/data_structures/llm.py
from pydantic import BaseModel
from typing_extensions import Self
from llm_agents_from_scratch.data_structures.tool import ToolCall
 
… #A
 
class ChatRole(str, Enum):
    """Roles for chat messages."""
 
    USER = "user"
    ASSISTANT = "assistant"
    SYSTEM = "system"
    TOOL = "tool"
 
class ChatMessage(BaseModel):
    """The chat message data model.
 
    Attributes:
        role: The role of the message.
        content: The content of the message.
        tool_calls: Tool calls associated with the message.
    """
 
    model_config = ConfigDict(arbitrary_types_allowed=True)
    role: ChatRole
    content: str
    tool_calls: list[ToolCall] | None = None #B
 
    @classmethod #C
    def from_tool_call_result(
        cls,
        tool_call_result: ToolCallResult
    ) -> Self:
        """Create a ChatMessage from a ToolCallResult."""
        return cls(
            role=ChatRole.TOOL, #D
            content=tool_call_result.model_dump_json(indent=4), #E
        )

The implementation defines the role enum, message fields, and tool-result constructor interface. section 3.1.1

The asynchronous chat() interface takes an input string, optional ChatMessage history, and optional tools. It returns a user message and an assistant message; append both to the running history for the next invocation. The assistant message can contain ToolCall objects, including when its content is an empty string. section 3.1 section 3.1.1

To complete a tool interaction, execute the requested ToolCall objects and send their ToolCallResult objects back using continue_chat_with_tool_results(). It returns a list of TOOL messages and an assistant response; append both to the history. ChatMessage.from_tool_call_result() constructs a TOOL message whose content is a string serialization of the result. section 3.1.2 section 3.1.1

A Hailstone tool call

A chat request asks for the next Hailstone step from 3. The assistant message requests the Hailstone tool with x=3; executing it produces a result containing 10. Passing that result and the prior messages to continue_chat_with_tool_results() yields tool messages and an assistant response with content '10'. section 3.2.2

In an agent task step, messages can also carry the previous rollout and the current instruction to the backbone LLM. The agent acts as USER, the backbone LLM as ASSISTANT, and tool results return through TOOL messages. This implementation permits one tool-calling phase per step. section 4.2.3

How Build a Multi-Agent System (from Scratch) covers it

How deep it goes
Defines the message schema and roles, then traces chat history updates and tool-result conversion through the interfaces.
Examples
Demonstrates a Hailstone tool call for input 3 and an agent task step using rollout context.
What you can do after
Build it from scratch as a typed message model and use it to maintain chat history across tool calls.
How it connects
Connects chat history, message roles, tool calling, and LLM agents.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Build a Multi-Agent System (from Scratch). The section links point to the parts of the book it draws on.