Examples

Examples

The repository keeps runnable examples under examples/. Run every command from the repository root.

The catalog below is an annotated tour of every example, ordered from the simplest local graph to the most deeply recursive — an agent that authors and runs its own workflow. For each example: what it shows, how to run it, and which recursive-language-model (RLM) concept it demonstrates.

Examples whose name starts with openai_ (plus orchestrator_subagents) call a real hosted provider and require the openai Cargo feature and an API key:

export OPENAI_API_KEY=...        # or copy .env.example to .env
cargo run --features openai --example <name>

The default build is offline: basic_graph, complex_graph, durable_graph, agent_loop_tools, and rag_blueprint run with no key and no feature flag.

---

1. basic_graph (offline)

cargo run --example basic_graph

A minimal durable graph: a whole-state agent/tool loop. A GraphBuilder over Update == State (the overwrite reducer, so each node returns the full next state) wires an agent node and a tool node. Conditional edges route agent -> tool while needs_tool is set, otherwise agent -> END; tool clears the flag and loops back to agent.

Recursive concept: the base case. A typed state graph is a loop — a model node and a tool node calling each other until a condition ends the run. This is the smallest unit the deeper examples nest and compose.

2. durable_graph (offline)

cargo run --example durable_graph

Durable execution with partial updates, a reducer, and checkpointing. State is a Counter; each node returns a small i64 partial update, and a ClosureStateReducer folds updates into the running counter while appending an audit-log line. The graph runs on a thread backed by an InMemoryCheckpointer, and the example lists the checkpoints written at each superstep boundary.

Recursive concept: durability/observability of a run. Checkpoints make each superstep an inspectable value — the persistence foundation that lets a parent pause, resume, and reason about a child computation.

3. complex_graph (offline)

cargo run --example complex_graph

A nested subgraph embedded inside a parallel fan-out / join. dispatch fans out (via Command::goto) into two branches that run concurrently. One branch (branch_sub) is a subgraph embedded with adapter_subgraph_node; its child itself embeds a grandchild via shared_subgraph_node, so a value flows up through two subgraph levels (0 -> +5 -> +1 = 6). The reducer deterministically joins the branches before join finalizes.

Recursive concept: graphs that run graphs. A node embeds another compiled graph, which embeds another — a subgraph inside a subgraph — the structural form of recursion in the graph runtime.

4. agent_loop_tools (offline)

cargo run --example agent_loop_tools

The harness agent loop end-to-end with a real tool and no network. A ScriptedModel is scripted to first request a tool call, then (after seeing the tool result) produce a final answer. A small CalculatorTool (add) is registered so the loop has something to run. This is the canonical model→tool→model loop that every higher example builds on.

Recursive concept: the harness agent loop — the substrate. A sub-agent is just this loop invoked one level deeper, so understanding it is the key to the recursive examples.

5. openai_chat (needs --features openai)

cargo run --features openai --example openai_chat

The simplest hosted happy path: register an OpenAiModel in an AgentHarness, set it as the default model, run one question through the default agent loop, and print the answer plus token usage.

Recursive concept: the leaf call. A single provider-neutral model invocation — the atom that recursion is built from.

6. openai_tools (needs --features openai)

cargo run --features openai --example openai_tools

The full tool-calling loop against a real provider. A local get_weather Tool is registered alongside an OpenAiModel; a question triggers the tool, the harness runs it locally, feeds the result back, and the model produces the final answer.

Recursive concept: model → tool → model over the network. The tool boundary here is exactly the boundary a sub-agent later occupies.

7. openai_structured (needs --features openai)

cargo run --features openai --example openai_structured

Schema-constrained output. RunPolicy::default_response_format is set to a ResponseFormat::json_schema describing a {sentiment, score} object; the harness attaches it to every request and extracts the parsed JSON into the run's structured response.

Recursive concept: typed channels between levels. Structured output is how a parent reliably reads a child's result as data — the typed wire an orchestrator needs to route on a sub-agent's answer.

8. openai_graph_agent (needs --features openai)

cargo run --features openai --example openai_graph_agent

A durable graph whose node drives a real OpenAI-backed harness. An AgentHarness is wrapped in an Arc, captured in a graph-node closure, and the graph runs START -> agent -> END: the node calls the harness (which talks to OpenAI), stores the answer in graph state, and ends.

Recursive concept: the two runtimes compose. The durable graph runtime and the harness agent loop nest cleanly — a graph node is an agent — which is what makes graph→agent→graph recursion possible.

9. orchestrator_subagents (needs --features openai)

cargo run --features openai --example orchestrator_subagents

Flagship registry showcase: an orchestrator that designs which sub-agents to call at runtime. Several specialized SubAgents (researcher, coder, summarizer) — each an OpenAiModel with a distinct system prompt — are wrapped as SubAgentTools and registered by name in a CapabilityRegistry. The flow:

1. Register named capabilities.
2. Discover the available names + descriptions back out of the registry (nothing hard-coded into the planner).
3. Design — an orchestrator agent, given the task plus the discovered menu, decides via structured output which sub-agents to invoke.
4. Bind at runtime — each chosen name is resolved with CapabilityRegistry::tool, the sub-agents run in parallel (join_all), and their results are composed into a final answer.

Recursive concept: agents calling agents. A model decides which other agents to run, then runs them as tools — orchestration is one model invoking models, with capabilities named, discovered, and bound at runtime rather than wired in statically.

10. rag_blueprint (offline)

cargo run --example rag_blueprint

Compiles the spec's support_agent .rag blueprint. The example parses the expressive-language source into a Program, compiles it into a Blueprint, prints the node/edge/route structure, then bind_capabilities resolves the blueprint's referenced model and tools against a CapabilityResolver.

Recursive concept: programs as runtime values. A declarative .rag workflow lowers — lexer → parser → compiler — into the same graph/harness runtime as hand-written Rust. This is the human-authored half of self-authoring, and the safe boundary the next example lets a model write into.

11. openai_self_blueprint (needs --features openai)

cargo run --features openai --example openai_self_blueprint

The deepest recursion: the agent authors its own graph. OpenAI is asked to emit only .rag source for a small agent graph (given the grammar plus a worked example), the .rag text is extracted from the reply, then run through the same safe pipeline as a human-authored blueprint: parse_str -> compile -> print the Blueprint -> bind_capabilities against a CapabilityResolver allowlist (the policy gate — only allowlisted models/tools pass) -> build_graph with a NodeFactory -> run to END. The model never executes code; it only produces declarative source that a Rust-side factory materializes, and the capability allowlist is the safety boundary. Parse/compile failures print the diagnostic and the offending source instead of panicking.

Recursive concept: self-authoring — a model emits a blueprint that compiles through the same registry-bound compiler path and runs on the same runtime the model is already executing in. The harness describes and re-enters itself, with the capability allowlist as the policy gate.

---

Where to go next

• Harness — the agent loop, sub-agents, steering, and the surfaces these examples drive.
• Graph Runtime — subgraphs, reducers, and checkpointing.
• Providers — configuring OpenAiModel and compatible hosts.