Expand description
§Rusty Core
Rusty Core (the rusty-agent-runtime crate) is a LangGraph-style agentic
core engine in Rust. It models
agent workflows as cyclic graphs over shared state:
- State & channels (
state): every state key is a channel with a per-keystate::Reducerdefining merge semantics. Nodes return partial updates; the engine merges them via reducers.LastValue-style channels (the default) accept at most one write per super-step, otherwise anerror::RustyError::InvalidUpdateis raised. - Nodes (
node): async functions (ornode::Nodetrait impls) receiving anode::NodeContext(immutable state snapshot + config + interrupt/resume helpers) and returning anode::NodeOutput— partial state updates plus an optionalnode::Commandfor dynamic routing. - Graph (
graph): a thin builder (graph::GraphBuilder) with normal edges, conditional edges returning agraph::Route(including dynamic fan-out viagraph::Send), and structural validation when you callgraph::GraphBuilder::compile. - Execution (
executor): a Pregel/BSP-inspired super-step loop — plan → run active nodes in parallel over an immutable snapshot → barrier → merge writes via reducers → route → checkpoint — emittingexecutor::GraphEvents for streaming. - Persistence (
checkpoint): thread-scoped, versioned snapshots via thecheckpoint::Checkpointertrait; includes an in-memory saver and a durable pure-serde_jsonfile saver, plus apostgres-featurePostgresCheckpointer(see thecheckpoint_postgresmodule). - LLM & tools (
llm,tool): allm::ChatModelabstraction with an OpenAI-compatible client, and atool::ToolRegistry/tool::ToolExecutorfor parallel tool-call dispatch — everything needed for the prebuilt ReAct pattern (react). - MCP (
mcp): call any MCP server’s tools fromtool::Toolimpls over stdio transport; MCP tool servers register into the registry/executor exactly like native tools. - Middleware (
middleware): ordered interception layers around node runs, model calls, and tool calls — observe, mutate, reject, or short-circuit with tower-style onion semantics. Layers attach to the executor viaexecutor::Executor::layer. - Remote nodes (
remote): aremote::RemoteNodeexecutes node work on a remote worker over HTTP behind the samenode::Nodetrait; HITL interrupts cross the wire. - A2A client (
a2a, R0.9 wave 4): ana2a::A2aNodedelegates a node’s work to a remote A2A agent behind the samenode::Nodetrait — journaled as one replay-servableRemoteCallevent with the derivedmessageIdidempotency handle, replay-served outcomes with no outbound calls, andtasks/cancelpropagation on run cancellation. - Durable work (
durable): the shared R0.6 contracts for effectively-once distributed activities — thedurable::ErrorClassretry taxonomy, thedurable::RetryDecisionpolicy mapping, and the serde-versioneddurable::TaskEnvelope. Queue, leases, and workers live inrusty-agent-server/rusty-worker; these are the pure contracts both sides agree on. - Agent fabric (
agents, R0.7): the durable-agent contracts — stableagents::AgentIdidentity with itsagent:{id}mailbox/thread addressing grammar, the versionedagents::CapabilityManifest(accepted message kinds, declaredagents::StateScopes, budget ceiling), the agentrecord::RunEventKindvariants (AgentSpawn,MailboxSend, …), and the typed coordination patterns (wave 3:agents::CoordinationContract— delegate / fan-out / race / quorum — with their outcomes and violation vocabulary). The registry, activation leases, turn-serialized mailbox, and the pattern runtime live inrusty-agent-server; these are the pure contracts both sides agree on.team_traceis the read-side half: it stitches verified journal snapshots back into one cross-journal causal tree. - Effect kernel v2 (
effects, R0.7): the R0.5record::Effecttaxonomy moved into the type system — marker traits declare an effect’s safety class at compile time, deterministiceffects::EffectIds let recovery ask whether an effect already committed, and irreversible effects execute only behind an expliciteffects::ApprovalToken. Opt-in: the untypedrecord::Effectpath behaves exactly as before. - Replay (
replay): exact replay of journaled runs — model, tool, remote, and WASM calls are served from the journal instead of executed — plus branch diffs between journal snapshots and portablereplay::ReplayFixturebundles for CI. - The runtime digital twin (
twin, R0.10 wave 2): deterministic re-execution of recorded runs that answers what plain replay cannot — seededtwin::FaultSchedules landing at decision points and the effect boundary, seeded schedule randomization of each super-step’s parallel task set, counterfactual branches over one changed decision compared asreplay::BranchDiffevidence, and shadow policies whose decisions journal with roles and propensities alongside the acting floor’s. Bounded by the honest edge: only decisions that change when and whether effects execute are evaluable, and everytwin::TwinReportsays so. - Governed memory (
memory, R0.8 wave 1): the record model (memory::MemoryRecord— content-addressed, scoped, attributed, superseding, expiring), structured retrieval with a token-bounded deterministic assembly (memory::MemoryQuery+memory::ContextBudget), and the journaled seam: reads arerecord::RunEventKind::MemoryRead(record::Effect::ReadOnly, served byte-identically by exact replay), writes arerecord::RunEventKind::MemoryWrite(record::Effect::Idempotentunder a derived key). The store backends and endpoints live inrusty-agent-server; these are the pure contracts both sides agree on. - Learning candidates (
learn, R0.8 wave 3): the candidate pipeline — content-addressedlearn::Candidates (identity is integrity), the evaluation composition seam (learn::CandidateEvaluatorwith its replay + experiment + verdict payload), the declaredlearn::PromotionEnvelopeand its gate (learn::admit_promotion, out-of-envelope promotions requiring a scopedeffects::ApprovalToken), canary binding by seeded draw, and the active-version pointer with byte-exact rollback. Every transition journals through theCandidateCreated/CandidateEvaluated/CandidatePromoted/CandidateRolledBackevent kinds. - The configuration registry (
registry, R0.11): the prompt/configuration registry — named, ownedregistry::ArtifactRecords indexing the candidate pipeline (a commit is a candidate, never a fork of it), environment tags on surface keys (learn::EnvironmentTag) so one deployment promotes per environment through the unchanged pointer machinery,registry::diff_candidatesviews computed on read, never stored, and admission-time resolution (wave 2): a run’s named artifacts bind through the tagged version pointer to a candidate (registry::pointer_admission) whose content the manifest pins by digest, the digest ↔ version join journaled asregistry::ConfigResolution. The store backends and endpoints live inrusty-agent-server; these are the pure contracts both sides agree on. - The credential/connection broker (
broker, R0.11 wave 3): no tool ever holds a raw credential. The connection entity (broker::ConnectionRecord— consent scope set as the ceiling everything narrows against, status, health), the sealed-storage shape (broker::StoredConnection— ciphertext and a wrapped data key only, plaintext on neither backend ever), and the handle lifecycle: short-lived, opaque, non-serializablebroker::CredentialHandles whose validity is self-contained in signed claims while revocation reads live connection state at every resolution — a revoked connection fails closed at the next tool call with a typed, journaledbroker::BrokerDenial.broker::CredentialMediator/broker::MediatedToolmediateToolExecutordispatch, and behindwasmbroker::BrokeredCapsuleHostturns capsuleSecretgrants into broker-issued handles; in both, resolution returns the credential bytes to the host-side connector, never to tool code. The store backends, envelope cryptography, master key, and endpoints live inrusty-agent-server; these are the pure contracts both sides agree on. - WASM nodes (
wasm_node, featurewasm): sandboxed WebAssembly modules run as graph nodes via Wasmtime. - Rusty Capsules (
capsule, R0.9 wave 1): the content-addressedcapsule::CapsuleManifest— identity, version, build digest, the declared WIT-world interface, the closedcapsule::CapabilityGrantset (the whole reach), and thecapsule::ResourceBudget— plus the journaled payloads (capsule::CapsuleResolution/capsule::CapsuleUse/capsule::CapsuleDenial) that make capability enforcement attributable. The capability host (capsule_host, featurewasm) instantiates components against the declared world with imports linked only where granted — deny by default, structurally — and the registry resolvingRunManifestcapsule pins to content addresses lives inrusty-agent-server; these are the pure contracts both sides agree on. - Signed run receipts (
receipt, R0.9 wave 3): the Ed25519-signedreceipt::RunReceiptover the journal head, the run manifest digests and resolved capsule ids, the effect and denials ledgers, and the policy versions — plusreceipt::verify_receipt, which re-walks the journal’s own digests and answers with a typedreceipt::VerifiedRunor areceipt::ReceiptRejectionnaming the mismatched component. The key lifecycle (first-boot generation, journaled rotation, the key history old receipts verify against) lives inrusty-agent-server; these are the pure contracts both sides agree on.
§Quick sketch
use rusty_agent_runtime::prelude::*;
let spec = StateSpec::new().channel("messages", Reducer::AddMessages);
let mut builder = GraphBuilder::new();
builder.add_node("agent", |ctx: NodeContext| async move {
let _state = ctx.state();
Ok(NodeOutput::update("messages", serde_json::json!({"role": "assistant", "content": "hi"})))
});
builder.set_entry_point("agent");
let graph = builder.compile()?;
let outcome = Executor::new()
.run(&graph, &spec, State::new(), RunConfig::new("thread-1"))
.await?;Modules§
- a2a
- A2A (Agent2Agent) client support:
A2aNode, the durable half of the A2A bridge (R0.9 Rusty Capsules, wave 4). - agents
- Agent Fabric contracts (R0.7): durable agent identity, the versioned capability manifest, the state-scope taxonomy, the supervision vocabulary (wave 2), and the typed coordination patterns (wave 3).
- artifact
- The run artifact plane (R0.12 Operations Plane, wave 1): the records that make a run’s binary outputs operable — content-addressed, lineage-carrying, retainable — plus the journaled commitment that binds each one back into the run’s evidence.
- broker
- The credential/connection broker contracts (R0.11 Extension Plane, wave 3): the connection entity, the sealed-storage shape, the handle lifecycle, and the seams that keep credential bytes out of tool code.
- capsule
- The capsule manifest contract (R0.9 Rusty Capsules, wave 1): the content-addressed declaration of what untrusted code may reach, and the journaled payloads that make its enforcement attributable.
- checkpoint
- Checkpointing: thread-scoped, versioned state snapshots.
- deploy
- The deployment control plane’s core contracts (R0.12 Operations Plane, wave 3): revisions, environments, and the per-environment deployment pointer, plus the journaled payloads of every control-plane act and the environment-scoped secret records.
- durable
- Durable Work contracts (R0.6): the shared retry taxonomy and task envelope.
- effects
- Effect kernel v2 (R0.7): retry-safety moves from runtime convention into the type system.
- error
- Error types for Rusty Core.
- executor
- The executor: a Pregel/BSP-inspired super-step run loop.
- graph
- Graph definition, plus structural validation when you call
GraphBuilder::compile. - journal
- The effect journal: the Flight Recorder’s append-only run evidence, plus
the determinism seams (
Clock,RngSource) that let a recorded run be re-driven exactly. - learn
- The learning loop’s candidate pipeline (R0.8 Rusty Learn, wave 3): the candidate contract, the evaluation composition seam, the promotion envelope and its gate, canary binding by seeded draw, and the active-version pointer with byte-exact rollback.
- llm
- LLM abstraction and an OpenAI-compatible chat client.
- mcp
- MCP (Model Context Protocol) client support.
- memory
- Governed memory (R0.8 Rusty Learn, waves 1–2): the record model, the structured retrieval contract with its token-bounded deterministic assembly, the journaled read/write seam, and — from wave 2 — the correction loop and the memory operations (consolidation, conflict detection, forgetting) as journaled, evidence-carrying transitions.
- middleware
- Middleware / Interceptor SDK: ordered layers around execution.
- node
- Node abstractions: the unit of computation in the graph.
- prelude
- Convenience re-exports of the main public API.
- react
- The prebuilt ReAct agent (LangGraph
create_react_agentparity). - receipt
- Signed run receipts (R0.9 Rusty Capsules, wave 3): an Ed25519-signed statement over evidence the Flight Recorder already keeps, and the verification API that re-walks that evidence.
- record
- Flight Recorder contracts: the canonical, serde-versioned evidence schema.
- registry
- The prompt/configuration registry (R0.11 Extension Plane, wave 1): named artifacts with an owner and a commit history, plus the diff views between committed versions.
- remote
- Remote node execution: the worker wire protocol +
RemoteNode. - replay
- The replay engine: exact replay, branch diff, and portable fixtures.
- state
- Shared state, channels, and reducers.
- team_
trace - TeamTrace: cross-journal trace assembly for the Agent Fabric (R0.7 wave 3).
- tool
- Tool abstraction, registry, and parallel tool-call dispatch.
- twin
- The runtime digital twin (R0.10 wave 2): a deterministic re-execution environment for recorded runs.