Messages

A conversation is a Vec<Message>. Messages support five roles that cover the full agent lifecycle.

Constructors

use orion_core::Message;

// Standard conversation
let sys  = Message::system("msg-1", "You are helpful.");
let user = Message::user("msg-2", "Hello!");
let asst = Message::assistant("msg-3", "Hi there!");

// Tool interaction
let result = Message::tool_result(
    "msg-4",            // message id
    "call-1",           // tool_call_id (links to the assistant's request)
    "read_file",        // tool name
    "file contents...", // result content
    false,              // is_error
);

Roles

System, User, Assistant, ToolCall, and ToolResult. Assistant messages can carry tool_calls; tool-result messages carry a tool_result that links back to the originating call via tool_call_id.

Fields

Every message has:

• an id,
• a timestamp,
• an optional token_count, which the agent leaves unset for a host that counts tokens itself to fill in (per-generation counts arrive as GenerationStats events),
• tool_calls - the calls an assistant message asked for, each with an id, name and arguments,
• tool_result - on a tool-result message, the ToolResult it carries, and
• pinned - see Pinning.

A ToolResult has tool_call_id, tool_name, content, is_error, and pending. pending marks a placeholder for a result still to come; it is left out when false and read as false when missing, so conversations saved by earlier releases load unchanged.

Pinning

Any message with pinned == true always survives pruning, regardless of budget or strategy:

let pinned = Message::user("msg-5", "Remember: the project is called Orion.").pinned();
// or toggle an existing message on the agent:
agent.set_pinned("msg-5", true);

Pruning is turn-aware, so a pinned message keeps its whole turn - no orphaned call/result pairs. See Context & budgets for how pruning works.

Persisting conversations

Because the conversation is a plain Vec<Message>, you can serialize it, store it, and restore it later with agent.replace_messages(saved_messages).

A tool result carries pending: true when it is a placeholder for a result still to come, so pending tool calls survive a save and restore. See Long-running work.