liveBook · Manning

Message

As explained in Designing AI Systems

A message is a structured conversational item containing a role and content, optionally accompanied by metadata for tool interactions.

A message is one structured entry in a conversation. Its role identifies the source or purpose, and its content normally holds text. Messages form an ordered history that a session stores and a model request can use as context. section 4.1 section 4.0

The core fields support both conversation and tool execution:

  • role distinguishes user input, assistant responses, system instructions, and tool results. section 4.1
  • content holds text, but can be null when an assistant requests a tool call instead of answering. section 4.1
  • tool_calls records requested functions, their arguments, and call IDs. A tool result uses tool_call_id to link back to its request, including when multiple calls run in parallel. section 4.1
  • timestamp records when the message was created; the service contract also includes an optional name field. section 4.1 section 4.2
Listing 4.1 Message dataclass representing a single entry in the conversation
@dataclass
class Message:
    role: str
    content: Optional[str] = None
    tool_calls: Optional[List[ToolCall]] = None    #A
    tool_call_id: Optional[str] = None    #A
    timestamp: datetime = field(default_factory=datetime.utcnow)
 
@dataclass  
class ToolCall:
    id: str    #B
    type: Literal["function"]
    function: Function
 
@dataclass 
class Function:
    name: str
    arguments: str    #C
 

The Python data model makes content and tool metadata optional and nests each function request inside a ToolCall. section 4.1

Appointment availability

A patient asks about openings. The assistant sends a message with null content and a check_availability tool call. The workflow executes it and returns a tool message with the matching call ID and available slots; the assistant then answers the patient. section 4.1

A workflow records and retrieves messages through the Session Service, then supplies conversation history in a Model Service chat request. Context-window limits mean a long history may need to be restricted before the next request. section 4.2 section 3.1.6 section 4.0

Listing 4.7 The Message structure and its nested types
message Message {
    string role = 1;
    optional string content = 2;
    repeated ToolCall tool_calls = 3;
    optional string tool_call_id = 4;
    optional string name = 5;
    int64 timestamp = 6;
}
 
message ToolCall {
    string id = 1;    #A
    string type = 2;
    Function function = 3;
}
 
message Function {
    string name = 1;
    string arguments = 2;    #B
}
 

The Protocol Buffer representation carries message fields and nested tool-call types across the service boundary. section 4.2

Using an OpenAI-style canonical message format keeps stored history and model requests familiar and minimizes translation for OpenAI and OpenAI-compatible vLLM endpoints. Provider adapters translate between this representation and other provider formats. section 3.2.3

How Designing AI Systems covers it

How deep it goes
Defines message fields and nested tool calls in Python and Protocol Buffers, with a worked tool-result sequence.
Examples
Traces a patient’s appointment query through an availability function, correlated tool result, and assistant answer.
What you can do after
Build message representations with optional tool-call metadata and correlate tool results with requests.
How it connects
Connects conversation memory, context windows, function calling, and provider adapters.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Systems. The section links point to the parts of the book it draws on.