Rusty Core
The durable agent runtime built in Rust — core graph engine. LangGraph's execution model, rebuilt on tokio, with Rust's safety and single-binary deployment.
Rusty Core models agent workflows as cyclic graphs over shared state. Every state key is a versioned channel with per-key reducer semantics; nodes are async functions returning partial updates; execution follows a Pregel/BSP super-step model with first-class checkpoints, interrupts, streaming events, and dynamic fan-out. Dual-licensed under MIT OR Apache-2.0.
Status: v0.5.0. The public API surface — modules, types, and trait signatures in
src/— is stable to build against. The state/reducer engine, the graph builder (validated when you callGraphBuilder::compile()), Pregel/BSP executor super-step loop, in-memory, JSON-file, and Postgres checkpointers, checkpoint time travel (get_by_id/fork_thread/RunConfig::with_checkpoint_id), sandboxedWasmNodeexecution (wasmfeature),ChatModelabstraction with token streaming, OpenAI-compatible client, parallelToolExecutor, the prebuilt ReAct agent (react::create_react_agent), the MCP client, remote nodes (RemoteNode), executortracinginstrumentation, and the Flight Recorder (canonical evidence contracts, per-run effect journal with determinism seams, exact replay, branch diff, portable replay fixtures) are implemented and tested, with five runnable examples underexamples/. An axum HTTP/SSE server lives in the siblingrusty-agent-servercrate, and OpenTelemetry export inrusty-otel. See the roadmap for what's next.
Why Rust?
Production agent runtimes spend their lives juggling hundreds of concurrent LLM streams, tool calls, and checkpoint writes. Rust buys you:
- No GC pauses, no GIL — deterministic streaming latency and true parallelism for concurrent tool calls on a single tokio runtime.
- Validation before execution — graph topology is validated when you call
compile(), before any node (or paid LLM call) runs; channel conflicts like double-writing aLastValuechannel surface as typed errors, not mid-conversation tracebacks. - Single-binary deployment — one static artifact, no interpreter, no dependency hell; a small, auditable dependency tree (tokio, serde, reqwest+rustls, thiserror).
- Memory footprint — no interpreter and no GC keep the resident set small, which matters when you colocate thousands of agent threads.
The trade-off is deliberate: you give up Python's runtime monkey-patching and get durable, auditable execution semantics in return.
Features
- Typed state channels with reducers — every state key is a channel with a per-key
Reducer:Overwrite(LangGraphLastValue, single-write per super-step),Append,DeepMerge, andAddMessages(ID-aware message upsert, LangGraphadd_messages). Writes to undeclared channels are rejected. - Pregel/BSP super-step executor — plan → run active nodes in parallel over an immutable snapshot → barrier → merge via reducers → route → checkpoint. The barrier makes shared-state parallelism safe: nodes in the same super-step can never observe each other's writes, and each step is transactional.
- Checkpointing — thread-scoped, versioned snapshots at super-step boundaries via the
Checkpointertrait. Ships withInMemoryCheckpointer(dev/test),JsonFileCheckpointer(durable, pureserde_json, no DB), andPostgresCheckpointer(sqlx-backed, behind thepostgrescargo feature). One primitive, four use cases: durable execution, human-in-the-loop, time travel, partial-failure recovery. - Human-in-the-loop interrupts — a node returns
Err(ctx.interrupt(payload))to suspend the whole run; the executor checkpoints and surfaces the payload viaExecutionOutcome::Interrupted. Resume with the samethread_idandRunConfig::with_resume(value); the interrupted node re-executes withctx.resume_value()set. - Dynamic fan-out (
Send) — conditional routers returnRoute::Send(vec![Send::new(node, state), ...])for runtime map-reduce: items are generated dynamically, each mapped through a node, results fan back in through multi-write reducers. - Streaming events — attach a
tokio::mpscsink viaRunConfig::with_event_txand receive typedGraphEvents (SuperStep,NodeStart,NodeEnd,StateUpdate,CheckpointSaved,Token); LangGraph'svalues/updates/messagesstream modes are filters over this one stream. - Token streaming —
ChatModel::chat_streamdelivers incrementalTokenChunks through a callback (the OpenAI-compatible client decodes real SSE deltas; the default impl falls back to one chunk for source compatibility). Forward them into the executor's event channel (Executor::with_token_tx/RunConfig::token_tx) to surfaceGraphEvent::Token(the LangGraphmessagesstream mode). - LLM & tool layer — a minimal
ChatModeltrait, anOpenAiCompatibleClient(works with OpenAI, vLLM, Ollama, LM Studio, Azure-compatible gateways), and aToolRegistry/ToolExecutorthat dispatches tool calls in parallel, preserves call order, and isolates per-tool failures: everything needed for the ReAct pattern. Commandrouting — nodes can override static edges withNodeOutput::route(Command::goto(...)), unifying state transition and control flow the way LangGraph'sCommanddoes.- MCP client (v0.3) — the
mcpmodule lets a Rusty CoreToolcall any MCP server's tools over stdio transport. MCP tool servers register intoToolRegistry/ToolExecutorexactly like native tools, so the prebuilt ReAct agent drives them with no graph changes. - Remote nodes (v0.3) — the
remotemodule'sRemoteNodePOSTs node execution to worker services over HTTP; the companionrusty-workercrate is the SDK that serves your handlers. HITL interrupts cross the wire: a remote node can suspend the run and resume with a human payload just like a local node. - Time travel (v0.4) — every checkpoint is a handle:
Checkpointer::get_by_idfetches any checkpoint of a thread,Checkpointer::fork_threadcopies a thread's history (full, or up to a checkpoint) into a new thread, andRunConfig::with_checkpoint_idreplays a run from that checkpoint's state and next-node set instead of the latest. Fork first, replay on the fork. - WASM nodes (v0.4, feature
wasm) —WasmNoderuns sandboxed WebAssembly modules as graph nodes via Wasmtime: untrusted or community code executes with capability isolation behind the sameNodetrait as local and remote nodes, with no separate worker fleet and no process boundary to manage. - Flight Recorder (v0.5) — every run is journaled as replayable evidence: canonical serde-versioned contracts (
RunEvent,DecisionEvent, theEffecttaxonomy,CheckpointHeader, golden-file pinned), an append-only per-run journal with causal parentage, content-addressed payloads, and a tamper-evident SHA-256 head hash stamped into checkpoints. InjectableClock/RngSourcedeterminism seams make a recorded run re-drivable, andExactReplayplus theRecording*/Replaying*wrappers re-run it with zero outbound calls — every model/tool/remote/WASM effect is served from the journal, verified event-for-event.BranchDiffcompares forked branches;ReplayFixtureexports a run as one portable JSON document for CI replay.
Quickstart
Rusty Core is published on crates.io as rusty-agent-runtime:
[]
= "0.5"
= { = "1", = ["full"] }
= "1"
A two-node graph with a conditional edge, run under a tokio runtime:
use *;
use json;
async
Add durable checkpoints and human-in-the-loop resume:
use *;
use json;
use Arc;
async
Time travel: fork & replay
Every checkpoint is a handle. Fork the thread's history into a branch, then replay the run from an earlier checkpoint on the fork, so the live timeline is left alone:
// Continuing the setup above: `checkpointer` and `executor` are in scope.
let history = checkpointer.list.await?; // oldest first
let first = history.id.clone;
// Copy history up to and including `first` into a branch thread
// (pass `None` to copy the full history).
let copied = checkpointer
.fork_thread
.await?;
println!;
// Replay the run from that checkpoint instead of the latest.
let replayed = executor
.run
.await?;
let _ = replayed;
Checkpointer::get_by_id fetches any single checkpoint by id; fork_thread preserves checkpoint ids, steps, states, and next-node sets; only the thread_id changes. The server crate exposes the same two operations over HTTP (POST /threads/{id}/fork and "checkpoint": {"checkpoint_id": …} on the run endpoints).
Flight Recorder: record → exact replay
Every run is journaled: the executor creates a Journal per run even when you attach nothing (retrieve it via Executor::journal). Attach your own journal with determinism seams — a logical clock and a seeded RNG — and the run's evidence becomes reproducible: same event ids, timestamps, and checkpoint ids on every drive. Inside nodes, wrap your model and tools with RecordingChatModel / RecordingTool so their calls journal in the canonical replay-compatible shapes:
use *;
// 1. Record: determinism seams make the evidence reproducible.
let journal = new;
let outcome = new
.run
.await?;
let snapshot = journal.snapshot; // serde-complete export; head-hash verified on load
// 2. Replay exactly: build the same graph topology with ReplayingChatModel /
// ReplayingTool wrappers over `replay.source()` — they answer from the
// journal and never invoke the wrapped implementations (zero outbound).
let replay = new?;
let params = new;
let replayed = replay
.run_and_verify
.await?; // RustyError::Replay on the first divergence, order violation, or shortfall
run_and_verify checks the replayed journal reproduces the recorded one event-for-event — payloads, artifacts, and the chained head hash included. Byte-identical replay requires the recorded run's clock/seed parameters and runs whose super-steps execute one node at a time (parallel steps interleave logical-clock reads by schedule). BranchDiff::between(&base, &branch) diffs two journals logically (first divergence, added/removed events, per-step channel diffs, token/cost totals), and ReplayFixture::{capture, export, import, replay_in_ci} packages a run — topology hash, journal, final checkpoint, determinism metadata — as one portable JSON document (FIXTURE_FORMAT_VERSION 1) for CI replay. The prebuilt ReAct agent has the wiring built in: create_react_agent_with_recording journals every model/tool call of the loop (canonical shapes, per-iteration causal parentage) and create_react_agent_replaying re-drives the recorded run under ExactReplay — see examples/react_record_replay.rs. The server persists journals per run and serves them over HTTP (GET /runs/{id}/events, GET /runs/{id}/fixture).
Architecture
┌─────────────────────────────────────┐
│ your application │
└───────────────┬─────────────────────┘
│ rusty_agent_runtime::prelude
┌────────────────────────────────┼────────────────────────────────┐
│ ▼ │
│ ┌──────────────┐ compiles ┌──────────────┐ │
│ │ graph │ ───────────► │ Graph │ frozen, Arc'd │
│ │ GraphBuilder │ validates │ nodes+edges │ topology │
│ └──────────────┘ └──────┬───────┘ │
│ ▲ Route / Send / Edge │ drives │
│ │ ▼ │
│ ┌──────────────┐ snapshots ┌──────────────────────────────┐ │
│ │ node │ ◄─────────── │ executor │ │
│ │ Node, │ NodeContext │ Pregel/BSP super-step loop: │ │
│ │ NodeOutput, │ ───────────► │ plan→parallel→barrier→merge→ │ │
│ │ Command │ NodeOutput │ route→checkpoint │ │
│ └──────────────┘ └───┬───────────────┬──────────┘ │
│ ▲ interrupt()/resume │ GraphEvent │ Checkpoint │
│ │ ▼ stream ▼ persist │
│ ┌──────────────┐ ┌────────────┐ ┌─────────────────┐ │
│ │ state │ │ your event │ │ checkpoint │ │
│ │ State, │ │ consumer │ │ Checkpointer, │ │
│ │ StateSpec, │ └────────────┘ │ InMemory / │ │
│ │ Reducer │ │ JsonFile │ │
│ └──────────────┘ └─────────────────┘ │
│ │
│ ┌──────────────┐ ┌────────────────────────────────┐ │
│ │ llm │ │ tool │ │
│ │ ChatModel, │ ◄─schemas─│ Tool, ToolRegistry, │ │
│ │ ChatMessage, │ │ ToolExecutor (parallel, │ │
│ │ OpenAi- │ ─messages►│ order-stable, error-isolating) │ │
│ │ Compatible │ └────────────────────────────────┘ │
│ │ Client │ │
│ └──────────────┘ │
│ │
│ error: one RustyError type; Interrupt is a typed suspend │
│ signal, not a failure. │
└─────────────────────────────────────────────────────────────────┘
Design rules worth knowing:
- Nodes never call nodes. They publish partial updates to channels; routing is decided by edges, routers, or
Commands at the barrier. - Cycles are not recursion. The ReAct loop
agent → tools → agentis nodes being re-scheduled across super-steps, guarded byRunConfig::max_steps(default 1000, matching LangGraph'srecursion_limit). - Node logic must be idempotent. Interrupt/resume and failure recovery re-execute a node from its start; checkpointing happens at super-step boundaries, never mid-node.
How it compares
vs. LangGraph (Python)
| Capability | LangGraph | Rusty Core |
|---|---|---|
| State graph with channels & reducers | ✅ Annotated[T, reducer] |
✅ StateSpec + Reducer (type-checked at build time) |
| Conditional edges & cycles | ✅ | ✅ (Route, Command::goto) |
| Checkpointing / durable execution | ✅ memory/SQLite/Postgres savers | ✅ Checkpointer trait + in-memory, JSON-file, and Postgres (postgres feature) implementations |
| Human-in-the-loop interrupts | ✅ interrupt() / Command(resume=) |
✅ ctx.interrupt() / RunConfig::with_resume |
Dynamic fan-out (Send API) |
✅ | ✅ Route::Send(Vec<Send>) |
| Streaming events | ✅ stream modes | ✅ typed GraphEvent stream over tokio::mpsc, incl. Token deltas (messages mode) |
| Parallel node execution | ✅ (asyncio) | ✅ (tokio JoinSet, no GIL) |
| Prebuilt ReAct agent | ✅ create_react_agent |
✅ react::create_react_agent(model, tools) assembles the standard agent → tools → agent loop |
| MCP tool interop | ✅ MCP adapters | ✅ mcp client module — call MCP servers' tools from Tool impls (v0.3) |
| Remote / distributed nodes | ✅ (LangGraph Platform workers) | ✅ RemoteNode + rusty-worker SDK, interrupts cross the wire (v0.3) |
| Time travel (fork / replay) | ✅ update_state + checkpoint history |
✅ Checkpointer::get_by_id / fork_thread + RunConfig::with_checkpoint_id (v0.4) |
| Sandboxed WASM nodes | ❌ | ✅ WasmNode via Wasmtime, behind the wasm feature (v0.4) |
| OpenTelemetry export | ✅ (LangSmith / OTel instrumentation) | ✅ rusty-otel crate: one-call subscriber setup + OTLP export (v0.4) |
| Ecosystem & integrations | ✅ huge | ❌ young — provider traits are designed to wrap Rig / async-openai / genai |
| Runtime cost | interpreter + GC | single static binary |
vs. existing Rust crates
Rig (rig-core) |
graph-flow / rs-graph-llm | adk-rust | Rusty Core | |
|---|---|---|---|---|
| Focus | Provider abstraction + agent builder (20+ providers) | Lean graph execution framework | Google ADK port: agent composition + A2A | Durable state-graph execution core |
| State graph with reducers | ❌ | ✅ basic | ❌ (sequential/parallel/loop agents) | ✅ |
| Checkpointing / resume | ❌ | 🟡 session persistence (Postgres); no versioned checkpoint model | ❌ | ✅ versioned, thread-scoped; time-travel listing |
| HITL interrupts | ❌ | 🟡 WaitForInput pause |
❌ | ✅ interrupt → checkpoint → resume protocol |
Send-style fan-out |
❌ | ❌ | ❌ | ✅ |
| Maturity | ~8k stars, production users | ~350 stars, single maintainer | ~570 stars, v1.0 (2026) | v0.4.0 |
Positioning: Rusty Core is the orchestration core, not another provider client. Its ChatModel trait is deliberately minimal so you can bring Rig, async-openai, or genai as the provider layer — the same pairing graph-flow demonstrates. The wedge no Rust crate ships today is the LangGraph quartet (state graph + durable checkpointing + HITL interrupts + resumable execution) as first-class, production-grade primitives.
Examples
Runnable examples live under examples/:
| Example | What it shows |
|---|---|
react_agent.rs |
The prebuilt ReAct loop via react::create_react_agent: agent node calling a ChatModel, tools node running ToolExecutor::execute_batch, conditional routing on pending tool calls — run with cargo run --example react_agent |
react_record_replay.rs |
Flight Recorder on the prebuilt ReAct agent: record with create_react_agent_with_recording, then exact-replay with create_react_agent_replaying over panic-on-call sentinels — zero outbound calls, byte-identical journal — run with cargo run --example react_record_replay |
parallel_fanout.rs |
Dynamic map-reduce: Route::Send fan-out over generated topics, parallel process_item workers, fan-in via Reducer::Append — run with cargo run --example parallel_fanout |
human_in_loop.rs |
Interrupt → durable JsonFileCheckpointer checkpoint → resume with a human approval payload — run with cargo run --example human_in_loop |
live_agent.rs |
A live ReAct agent against a real OpenAI-compatible endpoint (Ollama, OpenAI, vLLM, LM Studio) with token streaming — run with cargo run --example live_agent; exits gracefully with setup instructions when no endpoint is reachable |
See examples/README.md for a guided tour of all five.
Roadmap
- Executor super-step loop — the Pregel/BSP plan → parallel → barrier → merge → route → checkpoint algorithm in
executor.rs✅ implemented -
JsonFileCheckpointer— pure-serde_jsondurable file persistence ✅ implemented - Postgres checkpointer —
sqlx-backedPostgresCheckpointerbehind thepostgrescargo feature ✅ implemented in v0.2.0 - Prebuilt ReAct agent — one-call
react::create_react_agent(model, tools)assembling the standard loop ✅ implemented - Token streaming —
ChatModel::chat_stream+GraphEvent::Token(themessagesstream mode) ✅ implemented in v0.2.0 - Live agent example —
examples/live_agent.rsagainst any OpenAI-compatible endpoint ✅ implemented in v0.2.0 - MCP client — call MCP tool servers (e.g. memory servers) from
Toolimpls over stdio ✅ implemented in v0.3.0 - Remote nodes +
rusty-worker—RemoteNodeexecutes nodes on remote worker services; HITL interrupts cross the wire ✅ implemented in v0.3.0 - Executor tracing —
tracingspans through the super-step loop ✅ implemented in v0.3.0 - Time travel —
Checkpointer::get_by_id/fork_thread+RunConfig::with_checkpoint_id; exposed over HTTP byrusty-agent-serverv0.3 (POST /threads/{id}/fork, checkpoint replay on run endpoints) ✅ implemented in v0.4.0 - WASM nodes — sandboxed
WasmNodeexecution via Wasmtime behind thewasmcargo feature ✅ implemented in v0.4.0 - OpenTelemetry — OTLP export per super-step/node/LLM call via the
rusty-otelcrate ✅ implemented in v0.4.0 (rusty-otelv0.1.0) - Flight Recorder contracts — canonical
RunEvent/DecisionEvent/Effecttaxonomy /CheckpointHeader(withformat_version), golden-file pinned undertests/golden/✅ implemented in v0.5.0 - Effect journal + determinism seams — per-run append-only journal with causal parentage, content-addressed payloads, and a tamper-evident head hash; injectable
Clock/RngSourcewith pre-R0.5 defaults ✅ implemented in v0.5.0 - Exact replay —
ExactReplay::{run, verify, run_and_verify}withRecordingChatModel/RecordingToolandReplayingChatModel/ReplayingTool; zero outbound calls by construction ✅ implemented in v0.5.0 - Branch diff + portable fixtures —
BranchDiff::betweenfork comparison;ReplayFixture(FIXTURE_FORMAT_VERSION1) withreplay_in_ci✅ implemented in v0.5.0 - ReAct Flight Recorder wiring —
create_react_agent_with_recording/create_react_agent_replayingjournal and exact-replay the prebuilt agent's model/tool calls ✅ implemented in v0.5.0 - Postgres checkpoint provenance —
rusty_checkpointspersistsCheckpoint.header/journal_refvia nullablejsonbcolumns (additive, idempotent auto-migration; pre-R0.5 rows decode to serde defaults) ✅ implemented in v0.5.0 - WASM target — run graphs in the browser or edge runtimes (sans native checkpointers)
- Provider adapters — thin
ChatModelimpls over Rig,async-openai,genai -
PyO3 / napi-rs bindings— rejected: the HTTP/SSE server is the polyglot interop layer; see docs/roadmap.md
The platform-wide roadmap — implemented phases, this cycle's workstreams, Phase C/D candidates — lives in docs/roadmap.md.
Contributing
See CONTRIBUTING.md. Good first issues: provider adapters (Rig, async-openai, genai) and GenAI semantic-convention span attributes in rusty-otel.
License
Dual-licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT License (LICENSE-MIT)
at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.