# Examples The repository keeps runnable examples under [`examples/`](../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: ```sh export OPENAI_API_KEY=... # or copy .env.example to .env cargo run --features openai --example ``` 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) ```sh 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) ```sh 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) ```sh 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) ```sh 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`) ```sh 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`) ```sh 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`) ```sh 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`) ```sh 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`) ```sh cargo run --features openai --example orchestrator_subagents ``` Flagship registry showcase: an orchestrator that *designs* which sub-agents to call at runtime. Several specialized `SubAgent`s (`researcher`, `coder`, `summarizer`) — each an `OpenAiModel` with a distinct system prompt — are wrapped as `SubAgentTool`s 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) ```sh cargo run --example rag_blueprint ``` Compiles the spec's `support_agent` `.rag` blueprint. The example parses the expressive-language source into a `Program`, `compile`s 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`) ```sh 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](Harness.md) — the agent loop, sub-agents, steering, and the surfaces these examples drive. - [Graph Runtime](Graph-Runtime.md) — subgraphs, reducers, and checkpointing. - [Providers](Providers.md) — configuring `OpenAiModel` and compatible hosts.