Conversations and messages
In Loom, a conversation is represented as an ordered list of messages. Because Loom is “state-first,” these messages are typically stored in your GraphState and passed to LLMs to provide context.
1. Message Roles
Loom defines four core roles, each representing a different participant in the conversation:
| Role | Description | Concrete Type |
|---|---|---|
| System | High-level instructions for the model (e.g., “You are a helpful assistant”). | message.System |
| User | Messages sent by the human user. | message.User |
| Assistant | Responses generated by the AI model. | message.Assistant |
| Tool | The result of an external tool execution. | message.Tool |
Creating Messages
import "github.com/masterkeysrd/loom/message"
systemMsg := message.NewSystemText("You are a math tutor.")userMsg := message.NewUserText("What is the square root of 144?")2. Content Blocks
Loom messages are composed of one or more Blocks. This flexible structure supports multimodal inputs and advanced features like “chain-of-thought” thinking.
Text Blocks
The most common block type, used for simple text.
block := &message.TextBlock{Text: "Hello!"}Multimodal Blocks (Images, Audio, Video, Documents)
You can attach images (ImageBlock), audio (AudioBlock), video (VideoBlock), or documents/PDFs (DocumentBlock) to messages.
imageMsg := message.NewUserImage(imageData, "image/png")// OR via URLimageMsg := message.NewUserImageURL("https://example.com/photo.jpg")Caution. Strict Modality Validation (Zero Silent Drops): Loom never silently ignores or drops media blocks (
ImageBlock,AudioBlock,VideoBlock,DocumentBlock). If a known model profile does not list the modality inModalities.Inputs, or if the target provider’s wire protocol does not support that block type, role, or source mode (e.g., URL vs. inline bytes), the call fails immediately before spending tokens with an error matchingerrors.Is(err, profile.ErrUnsupportedModality). Historical*message.ThinkingBlockitems on priorAssistantturns remain lenient across providers.
Thinking Blocks
Some models (like Claude 3.5 or Gemini 2.0) can return their internal reasoning. Loom surfaces this as a ThinkingBlock.
// Access the thinking part of an assistant responsethinking := assistantMsg.Content.Thought()Tool Reference Blocks
Used to represent deferred tools that have been discovered or dynamically injected into the conversation. A ToolReferenceBlock signals to the LLM and provider mappings that the referenced tool is active and callable.
refBlock := &message.ToolReferenceBlock{ToolName: "convert_currency"}
// Injecting mid-conversation via a system or user message:msg := message.NewSystem(refBlock)Tool Definition Blocks
Used to inject a complete tool definition inline mid-conversation by value (for tools that were not pre-registered in the initial request.Tools catalog). Can be produced directly from a *tool.Tool or tool.Definition using .ToBlock().
defBlock := &message.ToolDefinitionBlock{ Name: "calculate_mortgage", Description: "Calculates monthly mortgage payments", InputSchema: schema,}// Or conveniently from an existing *tool.Tool:defBlock = myTool.ToBlock()
// Injecting mid-conversation via a user or system message:msg := message.NewUser( &message.TextBlock{Text: "Please calculate with this tool:"}, defBlock,)Server Tool Calls & Results
Represents provider-managed server-side tool calls (such as Anthropic or OpenAI tool_search, web_search, or file_search) and their outputs. Unlike standard *message.ToolCall blocks (which require local client execution via tool.Container), *message.ServerToolCall blocks are executed directly by the provider’s server and do not block local graph execution.
// Access server-side tool calls emitted by the assistantfor _, stc := range assistantMsg.ServerToolCalls() { fmt.Printf("Server tool: %s (ID: %s)\n", stc.Name, stc.ID)}
// Server tool results returned by the provider or client tool searchresultBlock := &message.ServerToolResult{ ToolCallID: "srv-call-1", Name: "tool_search", Content: message.Content{ &message.ToolReferenceBlock{ToolName: "calculate_mortgage"}, },}3. Managing History (MessageList)
A MessageList is a specialized slice of messages that provides critical functionality for state management and persistence. Always use MessageList instead of a raw []message.Message when storing history in your Graph State.
type MyState struct { History message.MessageList `json:"history"`}Why use MessageList?
- Polymorphic Serialization:
MessageListautomatically handles the complex task of serializing different message types (User, Assistant, etc.) into a single JSON array with a “role” discriminator. - Type-Safe Deserialization: When loading a checkpoint from a database (SQL or PG),
MessageListensures that raw JSON is correctly restored into the proper Go structs. - Fluent Helpers: Provides methods like
Last()andText()to easily access content without range loops.
history := message.MessageList{ message.NewSystemText("..."), message.NewUserText("..."),}
// Add a new responsehistory = append(history, assistantResponse)4. Token Metrics
Loom tracks token usage for every assistant response. This information is attached to the message.Assistant struct.
if resp.Metrics != nil { fmt.Printf("Input: %d, Output: %d, Total: %d, Estimated Cost: %s\n", resp.Metrics.Tokens.Input, resp.Metrics.Tokens.Output, resp.Metrics.TotalTokens, resp.Metrics.TotalCost)}5. Message Extensions & Metadata
Loom provides two ways to attach auxiliary information to a message:
Extensions (Type-Safe Hints)
Extensions are provider-specific structs that influence model behavior. Unlike raw metadata, Extensions are type-safe and are automatically restored to their concrete types when loaded from storage.
Loom provides two methods for adding extensions:
WithExtension(Fluent): Available on concrete message types (User,Assistant, etc.). It returns the same concrete type, allowing for method chaining without type erasure.AddExtension(Polymorphic): Available on theMessageinterface. Use this when you are working with a generic message object.
// 1. Fluent usage (preserves *message.User type)msg := message.NewUserText("Analyze this..."). WithExtension(&loomanthropic.MessageCache{Enabled: true})
// 2. Interface usagevar m message.Message = msgm.AddExtension(&someother.Extension{})Metadata (Arbitrary Data)
Metadata is a simple map[string]any for application-level data (IDs, timestamps, custom flags) that doesn’t need a formal schema.
msg.Metadata["session_id"] = "xyz-123"Summary
- Roles: Use
System,User,Assistant, andToolto distinguish participants. - Blocks: Mix and match
TextBlock,ImageBlock, andThinkingBlockfor rich interactions. - MessageList: Use this type to manage and persist your conversation history in your graph state.