Graph workflows
The graph package is the core execution engine of Loom. It provides primitives for defining, executing, streaming, and persisting multi-step AI agent workflows as directed graphs.
Loom is built on a State-First architecture. Rather than managing sprawling control flow, nested loops, and side-effects in unstructured application code, you define an explicit graph where each node transforms a strongly-typed shared state.
After setup, the router chooses the next step based on the current state.
| Route | Next step | Where it leads |
|---|---|---|
tools |
Execute a tool | Return to the router with the tool result. |
llm |
Generate a response | End the run. |
Architecture & Core Primitives
| Component | Type / Interface | Responsibility |
|---|---|---|
| State | graph.State[T] |
Shared workflow memory. Must implement Copy() T. |
| Builder | *graph.Builder[S] |
Fluent API for registering nodes, edges, middleware, safety limits, and persistence. |
| Node | graph.Node[S] |
A unit of execution that accepts the current state and returns a Command. |
| Node Function | graph.NodeFunc[S] |
Adapter function to convert standard Go functions into a graph.Node[S]. |
| Edge | Direct, Conditional, Route | Defines transitions between nodes. |
| Command | graph.Command[S] |
Instructions returned by nodes (Update, Interrupt, InterruptUpdate). |
| Graph | *graph.Graph[S] |
Immutable, compiled workflow engine created by builder.Build(). |
| Snapshot | graph.Snapshot[S] |
Point-in-time state snapshot including current values, next nodes, and location metadata. |
1. State (graph.State[T])
Every Loom workflow operates on a user-defined Go struct that satisfies the generic graph.State[T] interface:
type State[T any] interface { Copy() T}Writing a State Struct
Because Loom executes parallel nodes concurrently and supports checkpointing and time-travel, your Copy() method must ensure deep copy isolation for reference types (slices, maps, nested pointers):
package main
import "github.com/masterkeysrd/loom/message"
type AgentState struct { Query string `json:"query"` Messages message.MessageList `json:"messages"` Iteration int `json:"iteration"` NeedsReview bool `json:"needs_review"` Output string `json:"output"`}
// Copy creates an isolated copy of AgentState to prevent race conditions during execution.func (s AgentState) Copy() AgentState { clone := s if s.Messages != nil { clone.Messages = make(message.MessageList, len(s.Messages)) copy(clone.Messages, s.Messages) } return clone}Tip. Ensure all exported state fields include
jsontags. Loom checkpointers decompose state into channel-level JSON keys during persistence.
2. Commands: Directing the Engine
Nodes return a graph.Command[State] (and optional error) to notify the engine how state should change and whether execution should continue.
type Command[State any] interface { Apply(State) State}Built-in Commands
-
graph.Update[State](fn): Modifies state using a transformation functionfunc(State) State.return graph.Update[AgentState](func(s AgentState) AgentState {s.Iteration++return s}), nil -
graph.Interrupt(): Halts graph execution immediately. Loom persists the checkpoint to the configured checkpointer and returns the pausedSnapshotto the caller.if s.NeedsReview {return graph.Interrupt(), nil} -
graph.InterruptUpdate[State](fn): Modifies state and interrupts execution in a single atomic step. Used when a node (such as a sub-graph or a human-in-the-loop approval step) needs to record partial results before pausing.return graph.InterruptUpdate[AgentState](func(s AgentState) AgentState {s.Output = "Waiting on user confirmation"return s}), nil
3. Nodes & Edges
Defining Nodes with graph.NodeFunc
A node implements the graph.Node[State] interface:
type Node[State any] interface { Execute(context.Context, State) (Command[State], error)}Wrap inline functions cleanly with graph.NodeFunc[State]:
classifierNode := graph.NodeFunc[AgentState](func(ctx context.Context, state AgentState) (graph.Command[AgentState], error) { needsReview := len(state.Query) > 500 return graph.Update[AgentState](func(s AgentState) AgentState { s.NeedsReview = needsReview return s }), nil})Wiring Edges
Loom provides three types of edges to connect nodes:
-
Unconditional Edges (
AddEdge): Always transitions from source to destination.builder.AddEdge(graph.START, "classify")builder.AddEdge("execute", "summarize")builder.AddEdge("summarize", graph.END) -
Conditional Edges (
AddConditionalEdge): Branches based on a boolean predicate evaluated against current state.builder.AddConditionalEdge("classify", "human_review", func(s AgentState) bool {return s.NeedsReview})builder.AddConditionalEdge("classify", "automated_process", func(s AgentState) bool {return !s.NeedsReview}) -
Route Edges (
AddRouteEdge): Computes a route key dynamically and maps it to a target node.builder.AddRouteEdge("decide", func(s AgentState) (string, error) {if s.Iteration > 3 {return "escalate", nil}return "retry", nil}, map[string]string{"escalate": "manager_review","retry": "worker_node",})
Note.
graph.STARTandgraph.ENDare reserved virtual nodes representing graph entry and termination points.
4. Parallel Node Execution (Fan-out / Fan-in)
Loom natively supports concurrent execution. When multiple outgoing edges emerge from a node (or from START), the engine executes target nodes in parallel using goroutines.
In this example, three nodes fetch documents, the user profile, and permissions in parallel. Once all three finish, one node synthesizes the response and the graph ends.
builder := graph.New[AgentState]()
// Fan-out: START branches into three parallel nodesbuilder.AddEdge(graph.START, "fetchDocs")builder.AddEdge(graph.START, "fetchUserProfile")builder.AddEdge(graph.START, "fetchPermissions")
// Fan-in: all branches converge on a single aggregator nodebuilder.AddEdge("fetchDocs", "synthesize")builder.AddEdge("fetchUserProfile", "synthesize")builder.AddEdge("fetchPermissions", "synthesize")builder.AddEdge("synthesize", graph.END)Parallel Execution Semantics
- State Isolation: Before invoking each branch, Loom clones the current snapshot via
snapshot.State.Copy(). Parallel nodes execute concurrently without shared memory race conditions. - Deterministic Merge: Commands returned by parallel nodes are collected and applied sequentially in slice/edge order:
applyAll := func(s State) State {for _, cmd := range cmds {if cmd != nil {s = cmd.Apply(s)}}return s}
- Fan-in Deduplication: When multiple parallel edges converge on the same target (such as
"synthesize"above), Loom deduplicates the downstream node list while preserving encounter order. The join node runs exactly once. - Error Handling: If any concurrent node returns an error, execution stops immediately, and Loom returns the first encountered error formatted as
failed to execute node: %w. - Interrupt Handling: If any concurrent node returns an
Interruptablecommand (likeInterrupt()orInterruptUpdate), the merged result is promoted to an interrupt, pausing execution and saving the updated state. - Safety Step Tracking: Every executed parallel node increments the execution step counter against the configured
WithMaxStepslimit.
5. Sub-graphs as Nodes (AsNode & MapNode)
Sub-graphs enable composable, hierarchical agent architectures. A sub-graph is an independently defined, fully compiled Graph embedded as a node inside a parent graph.
Same-State Sub-graphs (childGraph.AsNode())
When child and parent share the exact same state struct, convert the compiled child graph directly with .AsNode():
// 1. Build the child research graphchildBuilder := graph.New[AgentState]().WithName("researcher")childBuilder.AddNode("search", searchNode)childBuilder.AddNode("summarize", summarizeNode)childBuilder.AddEdge(graph.START, "search")childBuilder.AddEdge("search", "summarize")childBuilder.AddEdge("summarize", graph.END)childGraph, _ := childBuilder.Build()
// 2. Embed inside parent coordinator graphparentBuilder := graph.New[AgentState]().WithName("coordinator")parentBuilder.AddNode("setup", setupNode)parentBuilder.AddNode("research", childGraph.AsNode()) // <-- Sub-graph nodeparentBuilder.AddNode("deliver", deliverNode)
parentBuilder.AddEdge(graph.START, "setup")parentBuilder.AddEdge("setup", "research")parentBuilder.AddEdge("research", "deliver")parentBuilder.AddEdge("deliver", graph.END)
parentGraph, _ := parentBuilder.Build()Different-State Sub-graphs (graph.MapNode)
When a sub-graph requires a specialized child state, use graph.MapNode to adapt parent state to child state and back:
type ParentState struct { UserID string `json:"user_id"` RawQuestion string `json:"raw_question"` Answer string `json:"answer"`}
func (s ParentState) Copy() ParentState { return s }
type MathState struct { Expression string `json:"expression"` Result float64 `json:"result"`}
func (s MathState) Copy() MathState { return s }
// childMathGraph operates on MathStatemathGraph, _ := mathBuilder.Build()
// Adapt mathGraph to parent's ParentStatemathNode := graph.MapNode( mathGraph.AsNode(), // toChild: extract ChildState from ParentState func(parent ParentState) MathState { return MathState{Expression: parent.RawQuestion} }, // fromChild: integrate ChildState updates back into ParentState func(parent ParentState, child MathState) ParentState { parent.Answer = fmt.Sprintf("Result: %.2f", child.Result) return parent },)
parentBuilder.AddNode("calculator", mathNode)Hierarchical Checkpoint Namespaces
When saving checkpoints across nested sub-graphs, Loom scopes state storage into LangGraph-style hierarchical namespaces:
CheckpointNS = parent_ns | node_name:task_id
Examples:
- Root level:
""(empty string) - First sub-graph level:
"research:83a1b0fe..." - Nested sub-graph level:
"research:83a1b0fe...|web_search:c593d18e..."
Namespace Guarantees:
- Deterministic Task IDs: Loom derives
task_iddeterministically via SHA-1 of(ThreadID, CheckpointNS, Step, NodeName). - Interrupt & Resume Isolation: When a sub-graph interrupts, the parent location preserves the execution step counter. On resume, the sub-graph receives the exact same
CheckpointNSand picks up directly from its last saved child checkpoint. - Loop Separation: Loops across distinct graph steps compute different task IDs, preventing collisions across repeated iterations.
- Node Name Restrictions: Because
|is the namespace separator (NSSep) and:is the task separator (NSEnd), node names cannot contain|or:. Slashes (e.g."tools/search"or"agent/writer") are fully supported.
Interrupt Propagation
If any node inside a sub-graph returns an Interrupt() or InterruptUpdate:
- Sub-graph execution halts and persists its internal child checkpoint.
AsNode()orMapNodecatches the incomplete snapshot (!snap.IsDone()).AsNode()/MapNodereturns anInterruptUpdatecommand to the parent engine.- The parent graph pauses, records all mutations up to the interrupt point, and returns the snapshot to the caller.
6. Execution Safety (WithMaxSteps)
Cyclic agent workflows (e.g. reflection loops, tool-retry cycles) can risk infinite execution if an exit condition is never reached. Loom provides rigorous safeguards:
builder := graph.New[AgentState](). WithMaxSteps(25) // Limit total node executions to 25
g, _ := builder.Build()
snapshot, err := g.Execute(ctx, initialCmd, nil)if errors.Is(err, graph.ErrMaxStepsExceeded) { log.Printf("Safety limit reached: %v", err)}- Step Counting: Virtual
STARTis not counted. Each invoked user node (including parallel nodes) increments the step count. - Dynamic Override: You can also set or adjust limits after building via
g.SetMaxSteps(limit). - Context Cancellation: Loom validates
ctx.Err()at every loop iteration and aborts immediately if a context deadline or cancellation occurs.
7. Node Middleware & Retry Policies
Loom middleware allows you to intercept, wrap, log, and retry user node executions without polluting node business logic.
type Middleware[S any] func(Node[S]) Node[S]Middlewares are applied in registered order (outermost first) and wrap only real user nodes (virtual START and END are never wrapped).
func LoggingMiddleware[S any](logger *log.Logger) graph.Middleware[S] { return func(next graph.Node[S]) graph.Node[S] { return graph.NodeFunc[S](func(ctx context.Context, state S) (graph.Command[S], error) { logger.Printf("entering node execution") cmd, err := next.Execute(ctx, state) logger.Printf("exiting node execution with err=%v", err) return cmd, err }) }}
builder.WithMiddleware(LoggingMiddleware[AgentState](logger))Configurable Retry Middleware (RetryMiddleware)
Loom provides a built-in exponential backoff RetryMiddleware for transient failures (e.g. network timeouts, LLM rate limits):
retryPolicy := graph.RetryMiddleware[AgentState]( graph.WithMaxAttempts(4), // Total attempts including initial call (default: 3) graph.WithInitialWait(200*time.Millisecond), // Initial wait duration (default: 100ms) graph.WithMaxWait(10*time.Second), // Max wait cap (default: 5s) graph.WithMultiplier(2.0), // Exponential multiplier (default: 2.0) graph.WithShouldRetry(func(err error) bool { // Optional retry predicate // Skip retrying non-transient validation errors return !errors.Is(err, ErrBadRequest) }),)
builder.WithMiddleware(retryPolicy)Retry Middleware Safety:
- State Isolation: Before each retry attempt,
RetryMiddlewareclones state withstate.Copy(), guaranteeing failed runs do not contaminate retry attempts. - Cancellation Awareness: If
ctx.Done()triggers during backoff wait or node execution, the middleware stops immediately and returnsctx.Err().
8. Visualization (ToMermaid & MermaidURL)
Compile and visualize your graph structure for documentation, debugging, or Loom Studio rendering:
g, _ := builder.Build()
// Generate raw Mermaid diagram definitionmermaidText := g.ToMermaid()fmt.Println(mermaidText)
// Generate instant preview link via mermaid.inkimageURL := g.MermaidURL()fmt.Println("Graph Diagram Preview:", imageURL)Example Mermaid output:
graph TD START((START)) classify[classify] human_review[human_review] automated_process[automated_process] END((END)) START --> classify classify -. [conditional] .-> human_review classify -. [conditional] .-> automated_process human_review --> END automated_process --> END8. Compile-Time Graph Validation
Loom strictly validates graph topology and integrity when builder.Build() is called, catching structural configuration mistakes before execution begins:
g, err := builder.Build()if err != nil { log.Fatalf("invalid graph configuration: %v", err)}Validation Guarantees:
- Node Validation: Node names cannot be empty, reserved (
START,END), or contain namespace delimiters (|,:). Nodes cannot benil. - Entry & Terminal Integrity: The graph must declare at least one outgoing edge from
START. The terminalENDnode cannot have outgoing edges. - Dead-End Detection: Every user-defined node must define at least one outgoing edge (to another node or to
END). - Edge & Target Integrity: All edges must originate from known nodes and point to valid, registered destination nodes (edges cannot point back to
START). - Edge Predicate Integrity: Conditions for
ConditionalEdgeand routing functions/target maps forRouteEdgecannot be empty ornil.
Next Steps
- Persistence & State: Explore SQLite, PostgreSQL, and checkpoint storage.
- Human-in-the-Loop: Build interactive approval and review loops.
- Tools & Streaming: Stream LLM output and connect external agent tools.
- RAG Workflows: Ingest documents, create vector stores, and retrieve knowledge.