Skip to main content

Crate rusty_agent_runtime

Crate rusty_agent_runtime 

Source
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-key state::Reducer defining 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 an error::RustyError::InvalidUpdate is raised.
  • Nodes (node): async functions (or node::Node trait impls) receiving a node::NodeContext (immutable state snapshot + config + interrupt/resume helpers) and returning a node::NodeOutput — partial state updates plus an optional node::Command for dynamic routing.
  • Graph (graph): a thin builder (graph::GraphBuilder) with normal edges, conditional edges returning a graph::Route (including dynamic fan-out via graph::Send), and structural validation when you call graph::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 — emitting executor::GraphEvents for streaming.
  • Persistence (checkpoint): thread-scoped, versioned snapshots via the checkpoint::Checkpointer trait; includes an in-memory saver and a durable pure-serde_json file saver, plus a postgres-feature PostgresCheckpointer (see the checkpoint_postgres module).
  • LLM & tools (llm, tool): a llm::ChatModel abstraction with an OpenAI-compatible client, and a tool::ToolRegistry / tool::ToolExecutor for parallel tool-call dispatch — everything needed for the prebuilt ReAct pattern (react).
  • MCP (mcp): call any MCP server’s tools from tool::Tool impls 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 via executor::Executor::layer.
  • Remote nodes (remote): a remote::RemoteNode executes node work on a remote worker over HTTP behind the same node::Node trait; HITL interrupts cross the wire.
  • A2A client (a2a, R0.9 wave 4): an a2a::A2aNode delegates a node’s work to a remote A2A agent behind the same node::Node trait — journaled as one replay-servable RemoteCall event with the derived messageId idempotency handle, replay-served outcomes with no outbound calls, and tasks/cancel propagation on run cancellation.
  • Durable work (durable): the shared R0.6 contracts for effectively-once distributed activities — the durable::ErrorClass retry taxonomy, the durable::RetryDecision policy mapping, and the serde-versioned durable::TaskEnvelope. Queue, leases, and workers live in rusty-agent-server / rusty-worker; these are the pure contracts both sides agree on.
  • Agent fabric (agents, R0.7): the durable-agent contracts — stable agents::AgentId identity with its agent:{id} mailbox/thread addressing grammar, the versioned agents::CapabilityManifest (accepted message kinds, declared agents::StateScopes, budget ceiling), the agent record::RunEventKind variants (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 in rusty-agent-server; these are the pure contracts both sides agree on. team_trace is the read-side half: it stitches verified journal snapshots back into one cross-journal causal tree.
  • Effect kernel v2 (effects, R0.7): the R0.5 record::Effect taxonomy moved into the type system — marker traits declare an effect’s safety class at compile time, deterministic effects::EffectIds let recovery ask whether an effect already committed, and irreversible effects execute only behind an explicit effects::ApprovalToken. Opt-in: the untyped record::Effect path 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 portable replay::ReplayFixture bundles for CI.
  • The runtime digital twin (twin, R0.10 wave 2): deterministic re-execution of recorded runs that answers what plain replay cannot — seeded twin::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 as replay::BranchDiff evidence, 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 every twin::TwinReport says 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 are record::RunEventKind::MemoryRead (record::Effect::ReadOnly, served byte-identically by exact replay), writes are record::RunEventKind::MemoryWrite (record::Effect::Idempotent under a derived key). The store backends and endpoints live in rusty-agent-server; these are the pure contracts both sides agree on.
  • Learning candidates (learn, R0.8 wave 3): the candidate pipeline — content-addressed learn::Candidates (identity is integrity), the evaluation composition seam (learn::CandidateEvaluator with its replay + experiment + verdict payload), the declared learn::PromotionEnvelope and its gate (learn::admit_promotion, out-of-envelope promotions requiring a scoped effects::ApprovalToken), canary binding by seeded draw, and the active-version pointer with byte-exact rollback. Every transition journals through the CandidateCreated / CandidateEvaluated / CandidatePromoted / CandidateRolledBack event kinds.
  • The configuration registry (registry, R0.11): the prompt/configuration registry — named, owned registry::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_candidates views 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 as registry::ConfigResolution. The store backends and endpoints live in rusty-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-serializable broker::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, journaled broker::BrokerDenial. broker::CredentialMediator / broker::MediatedTool mediate ToolExecutor dispatch, and behind wasm broker::BrokeredCapsuleHost turns capsule Secret grants 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 in rusty-agent-server; these are the pure contracts both sides agree on.
  • WASM nodes (wasm_node, feature wasm): sandboxed WebAssembly modules run as graph nodes via Wasmtime.
  • Rusty Capsules (capsule, R0.9 wave 1): the content-addressed capsule::CapsuleManifest — identity, version, build digest, the declared WIT-world interface, the closed capsule::CapabilityGrant set (the whole reach), and the capsule::ResourceBudget — plus the journaled payloads (capsule::CapsuleResolution / capsule::CapsuleUse / capsule::CapsuleDenial) that make capability enforcement attributable. The capability host (capsule_host, feature wasm) instantiates components against the declared world with imports linked only where granted — deny by default, structurally — and the registry resolving RunManifest capsule pins to content addresses lives in rusty-agent-server; these are the pure contracts both sides agree on.
  • Signed run receipts (receipt, R0.9 wave 3): the Ed25519-signed receipt::RunReceipt over the journal head, the run manifest digests and resolved capsule ids, the effect and denials ledgers, and the policy versions — plus receipt::verify_receipt, which re-walks the journal’s own digests and answers with a typed receipt::VerifiedRun or a receipt::ReceiptRejection naming the mismatched component. The key lifecycle (first-boot generation, journaled rotation, the key history old receipts verify against) lives in rusty-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_agent parity).
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.