liveBook · Manning

OpenAI message format

As explained in Designing AI Systems

The OpenAI message format is a message representation in which a conversation is an array of objects containing fields such as role and content, with additional fields for tool invocation results.

The OpenAI message format represents a conversation as an array of message objects. Each message has a role and content; roles include system, user, assistant, and tool. A shared message representation lets a Model Service pass conversations through provider adapters and lets a Session Service persist them without changing their basic structure. section 3.2.3 section 4.8

[
  {"role": "system", "content": "You are a helpful assistant..."},
  {"role": "user", "content": "What documents do I need?"},
  {"role": "assistant", "content": "Please bring your insurance card..."}
]
 

A basic conversation uses system, user, and assistant messages in one array. section 3.2.3

A tool invocation adds fields to this structure. The assistant message can have null content and a tool_calls array containing an ID, function name, and arguments. A subsequent tool message carries the result in content and uses tool_call_id to link it to the request. Function arguments are stored as a JSON string, preserving the model’s output without parsing it on every read and write. section 3.2.3 section 4.1

{"role": "assistant", "content": null, "tool_calls": [{"id": "call_123", 
➥"function": {"name": "check_schedule", "arguments": "{\"date\": 
➥\"Tuesday\"}"}}]}
{"role": "tool", "tool_call_id": "call_123", "content": "Available slots: 
➥9am, 2pm, 4pm"}

The tool result refers back to the assistant’s invocation using the same call ID. section 3.2.3

A session must retain the complete exchange, including the assistant’s tool call, the tool result, and the final assistant response, so that later turns remain coherent. A message data model can also add a timestamp for context-window management; that timestamp is an implementation field rather than a substitute for the message’s role and content. section 4.8 section 4.1

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
 

This Python data model separates message fields, tool-call identifiers, and function arguments while adding a timestamp for session management. section 4.1

Content can also be an array of typed blocks, such as text and image blocks, rather than a string. An implementation that stores only strings must change its content serialization to support structured multimodal messages; the storage and retrieval patterns can remain the same. section 4.1

As a platform standard, the format reduces translation for OpenAI and OpenAI-compatible vLLM endpoints. Provider adapters still translate between the canonical representation and other provider conventions, such as a separate system prompt or parts-based messages. section 3.2.3 section 3.10

How Designing AI Systems covers it

How deep it goes
Defines message and tool-call fields, implements dataclasses, and describes multimodal serialization changes without implementing them.
Examples
Shows an appointment conversation, a scheduling tool call and result, and Python message dataclasses.
What you can do after
Evaluate/understand how to represent and persist complete conversations, including linked tool calls and results.
How it connects
Connects provider adapters, function calling, session storage, and context-window management.

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.