Crate tinyagents 

TinyAgents — a recursive language-model (RLM) harness for Rust

TinyAgents is a typed, durable runtime where language models call models, agents call agents, and graphs run graphs — and where a model can author, compile, and run the very workflow it is standing inside, all as inspectable, checkpointed, policy-checked Rust.

The “recursive” framing is the through-line of the whole crate, not a footnote. It is architected around the execution model described in “Recursive Language Models” (Alex L. Zhang, Tim Kraska, Omar Khattab, MIT CSAIL, 2025; https://arxiv.org/abs/2512.24601): rather than stuffing everything into one context window, a model treats long context as an external environment it interacts with through a REPL — examining, decomposing, and recursively calling sub-models over snippets. TinyAgents brings that idea to Rust as a production-shaped harness (sub-model / sub-agent / sub-graph calls as functions, persistent session values, depth tracking, and trajectory/event logging). It is inspired by and architected around the RLM execution model, not a reimplementation of the paper’s benchmarks.

The five surfaces

1. Harness (harness) — provider-neutral model calls, typed tools, middleware, structured output, streaming, usage/cost, retry/limits, cache, memory/embeddings, sub-agents, steering, and a testkit.
2. Graph runtime (graph) — LangGraph-style durable typed state graphs: START/END, nodes, conditional routing, Commands, fan-out, reducers/channels, Checkpoints, Interrupts, subgraphs, streaming, topology export, and per-thread productivity primitives — a durable ThreadGoal with graph-native continuation and a TaskBoard kanban — exposed as harness tools.
3. Registry (registry) — a named capability catalog (models, tools, agents, graphs, stores, middleware, policy) that .rag/.ragsh bind by name.
4. Expressive language .rag (language) — a declarative, side-effect-free blueprint format that compiles (lexer → parser → compiler) into the same graph/harness runtime; the safe boundary for agent-authored plans.
5. REPL language .ragsh (repl) — imperative, capability-bound interactive orchestration; the RLM/CodeAct loop surface.

The recursion story

Both .rag and .ragsh lower into the same graph + harness types as hand-written Rust — a language whose programs are the runtime that interprets them. A harness agent can be exposed as a tool to another agent (SubAgent, SubAgentTool, SubAgentSession), so orchestration is just a model calling a model; the runtime tracks parent/child run lineage and enforces a recursion cap (TinyAgentsError::SubAgentDepth). At the deepest level a model can emit a .rag blueprint that compiles through the same registry-bound path as a human-authored file and runs on the same runtime the model is already executing in (see examples/openai_self_blueprint.rs).

Provider features

Hosted and local providers (OpenAI plus the OpenAI-compatible endpoints for Anthropic, Ollama, DeepSeek, Groq, xAI, OpenRouter, Together, and Mistral) are compiled in unconditionally alongside the offline, deterministic harness::providers::MockModel. Three Cargo features gate optional, heavier dependencies instead: sqlite (embedded SQLite checkpointer, [graph::checkpoint::SqliteCheckpointer]), repl (embedded Rhai engine powering the .ragsh session runtime, [repl::session]), and rlm (the recursive-language-model runtime: a driver model writes code cells run in a sandboxed interpreter — embedded Rhai or an external Python/JavaScript process — whose only host surface is capability calls back into the registry).

Crate-root re-exports

For discoverability the most-used types from each surface are re-exported at the crate root, grouped below by surface (error, registry, language, harness, and graph).

Re-exports

pub use error::Result;

pub use error::TinyAgentsError;

pub use registry::AliasBinding;

pub use registry::CapabilityRegistry;

pub use registry::ComponentId;

pub use registry::ComponentKind;

pub use registry::ComponentMetadata;

pub use registry::DiagnosticSeverity;

pub use registry::ModelCapabilities;

pub use registry::ModelCatalog;

pub use registry::ModelCatalogEntry;

pub use registry::ModelCatalogSnapshot;

pub use registry::ModelCatalogSource;

pub use registry::ModelPricing;

pub use registry::ModelRouter;

pub use registry::RegistryDiagnostic;

pub use registry::RegistrySnapshot;

pub use registry::WorkloadRoute;

pub use language::capability_resolver::CapabilityResolver;

pub use language::capability_resolver::bind_capabilities;

pub use language::capability_resolver::bind_capabilities_with_registry;

pub use language::compiler::compile;

pub use language::compiler::compile_source;

pub use language::compiler::compile_with_provenance;

pub use language::resolver::Resolver;

pub use language::resolver::resolve_source;

pub use language::types::Blueprint;

pub use language::types::BlueprintProvenance;

pub use language::types::ChannelSpec;

pub use language::types::CommandSpec;

pub use language::types::EdgeSpan;

pub use language::types::EdgeSpec;

pub use language::types::IoFieldSpec;

pub use language::types::JoinSpec;

pub use language::types::NamedSpan;

pub use language::types::NodeSpec;

pub use language::types::Origin;

pub use language::types::Routing;

pub use language::types::SendSpec;

pub use language::diff::BlueprintDiff;

pub use language::diff::ChannelDiff;

pub use language::diff::FieldChange;

pub use language::diff::NodeDiff;

pub use language::diff::blueprint_diff;

pub use language::testkit;

pub use language::diagnostic::Diagnostic;

pub use language::diagnostic::Label;

pub use language::diagnostic::Severity;

pub use language::source::SourceFile;

pub use language::source::SourceId;

pub use language::source::SourceMap;

pub use language::span::Span;

pub use harness::embeddings::EmbeddingModel;

pub use harness::embeddings::InMemoryVectorStore;

pub use harness::embeddings::MockEmbeddingModel;

pub use harness::embeddings::Retriever;

pub use harness::embeddings::ScoredDoc;

pub use harness::embeddings::VectorStore;

pub use harness::embeddings::cosine_similarity;

pub use harness::subagent::SubAgent;

pub use harness::subagent::SubAgentSession;

pub use harness::subagent::SubAgentTool;

pub use harness::steering::SteeringCommand;

pub use harness::steering::SteeringCommandKind;

pub use harness::steering::SteeringHandle;

pub use harness::steering::SteeringOutcome;

pub use harness::steering::SteeringPolicy;

pub use harness::cancel::CancellationToken;

pub use harness::workspace::SharedRootWorkspace;

pub use harness::workspace::WorkspaceDescriptor;

pub use harness::workspace::WorkspaceIsolation;

pub use harness::observability::AgentCallLatency;

pub use harness::observability::AgentLatencyMetrics;

pub use harness::observability::AgentObservation;

pub use harness::observability::FanOutSink;

pub use harness::observability::HarnessEventJournal;

pub use harness::observability::HarnessStatusStore;

pub use harness::observability::InMemoryEventJournal;

pub use harness::observability::InMemoryStatusStore;

pub use harness::observability::JournalSink;

pub use harness::observability::JsonlSink;

pub use harness::observability::RedactingSink;

pub use harness::observability::StoreEventJournal;

pub use harness::observability::LangfuseAuth;

pub use harness::observability::LangfuseClient;

pub use harness::observability::LangfuseScore;

pub use harness::observability::LangfuseScoreValue;

pub use harness::observability::LangfuseTraceConfig;

pub use graph::BarrierArrivals;

pub use graph::Checkpoint;

pub use graph::CheckpointConfig;

pub use graph::CheckpointMetadata;

pub use graph::CheckpointSource;

pub use graph::CheckpointTuple;

pub use graph::Checkpointer;

pub use graph::ChildRun;

pub use graph::ChildRunSink;

pub use graph::ClosureReducer;

pub use graph::ClosureStateReducer;

pub use graph::Command;

pub use graph::CompiledGraph;

pub use graph::DurabilityMode;

pub use graph::END;

pub use graph::FileCheckpointer;

pub use graph::ForkId;

pub use graph::GraphBuilder;

pub use graph::GraphDefaults;

pub use graph::GraphEvent;

pub use graph::GraphExecution;

pub use graph::GraphInput;

pub use graph::GraphRunStatus;

pub use graph::InMemoryCheckpointer;

pub use graph::Interrupt;

pub use graph::NodeContext;

pub use graph::NodeResult;

pub use graph::PendingActivation;

pub use graph::RecursionFrame;

pub use graph::RecursionPolicy;

pub use graph::RecursionStack;

pub use graph::Reducer;

pub use graph::ResumeTarget;

pub use graph::Route;

pub use graph::RouteTarget;

pub use graph::RunTree;

pub use graph::START;

pub use graph::StateReducer;

pub use graph::StateSnapshot;

pub use graph::HarnessAgent;

pub use graph::HarnessSubAgent;

pub use graph::SubAgentBudget;

pub use graph::SubAgentInput;

pub use graph::SubAgentNode;

pub use graph::SubAgentOutput;

pub use graph::SubAgentPolicy;

pub use graph::subagent_node;

pub use graph::subagent_node;

pub use graph::Barrier;

pub use graph::BinaryAggregate;

pub use graph::Channel;

pub use graph::ChannelSet;

pub use graph::ChannelState;

pub use graph::ChannelUpdate;

pub use graph::Delta;

pub use graph::Ephemeral;

pub use graph::LastValue;

pub use graph::Messages;

pub use graph::NamedBarrier;

pub use graph::Topic;

pub use graph::Untracked;

pub use graph::GraphEventJournal;

pub use graph::GraphHealthSummary;

pub use graph::GraphLangfuseExporter;

pub use graph::GraphLatencyMetrics;

pub use graph::GraphNodeHealth;

pub use graph::GraphNodeLatency;

pub use graph::GraphObservation;

pub use graph::GraphStatusStore;

pub use graph::GraphStepLatency;

pub use graph::InMemoryGraphEventJournal;

pub use graph::InMemoryGraphStatusStore;

pub use graph::JournalGraphSink;

pub use graph::SpanMetadataFn;

pub use graph::StoreGraphEventJournal;

pub use graph::InMemoryTaskStore;

pub use graph::JsonlTaskStore;

pub use graph::OrchestrationControlOutcome;

pub use graph::OrchestrationTaskFilter;

pub use graph::OrchestrationTaskKind;

pub use graph::OrchestrationTaskRecord;

pub use graph::OrchestrationTaskResult;

pub use graph::OrchestrationTaskSpec;

pub use graph::OrchestrationTaskStatus;

pub use graph::OrchestrationTool;

pub use graph::OrchestrationToolKind;

pub use graph::SteeringRegistry;

pub use graph::TaskStore;

pub use graph::orchestration_tool_schema;

pub use graph::orchestration_tool_schemas;

pub use graph::orchestration_tools;

pub use graph::orchestration_tools_with_steering;

pub use graph::register_orchestration_tools;

pub use graph::goals::store as goal_store;

pub use graph::GoalProgress;

pub use graph::GoalTool;

pub use graph::GoalToolKind;

pub use graph::ThreadGoal;

pub use graph::ThreadGoalStatus;

pub use graph::TurnOutcome;

pub use graph::active_goal_context_block;

pub use graph::goal_gate_node;

pub use graph::goal_tools;

pub use graph::note_user_turn;

pub use graph::register_goal_tools;

pub use graph::run_continuation_tick;

pub use graph::todos::store as todo_store;

pub use graph::CardPatch;

pub use graph::TaskApprovalMode;

pub use graph::TaskBoard;

pub use graph::TaskBoardCard;

pub use graph::TaskCardStatus;

pub use graph::TodoTool;

pub use graph::TodosSnapshot;

pub use graph::normalise_board;

pub use graph::parse_status;

pub use graph::register_todo_tools;

pub use graph::render_markdown;

pub use graph::todo_tools;

pub use graph::parallel::FailurePolicy;

pub use graph::parallel::ItemOutcome;

pub use graph::parallel::ParallelOptions;

pub use graph::parallel::ParallelOutcome;

pub use graph::parallel::map_reduce;

pub use graph::ChannelInfo;

pub use graph::ConditionalEdgeInfo;

pub use graph::EdgeInfo;

pub use graph::GraphPolicySummary;

pub use graph::GraphTopology;

pub use graph::NodeInfo;

pub use graph::NodePolicySummary;

pub use graph::RouteInfo;

pub use graph::ValidationReport;

pub use graph::WaitingEdgeInfo;

pub use graph::testkit::GraphAssertions;

pub use graph::testkit::GraphEventRecorder;

pub use graph::testkit::GraphRun;

pub use graph::testkit::RetryCountingNode;

pub use graph::testkit::StreamCollector;

pub use graph::testkit::assert_graph;

pub use graph::testkit::failing_node;

pub use graph::testkit::fanout_node;

pub use graph::testkit::interrupting_node;

pub use graph::testkit::noop_node;

pub use graph::testkit::run_recorded;

pub use graph::testkit::scripted_route_node;

pub use graph::testkit::scripted_update_node;

pub use graph::testkit::subagent_fake_node;

pub use graph::testkit::subgraph_test_node;

Modules

error

Crate-wide error type and Result alias.

graph

TinyAgents graph runtime.

harness

Harness runtime modules — the execution layer of the recursive runtime.

language

Expressive language (.rag) — the declarative blueprint surface of the recursive runtime.

registry

Registry coordination and discovery primitives — the named capability catalog that makes TinyAgents recursive.

repl

REPL language (.ragsh) — capability-bound interactive orchestration; the RLM/CodeAct surface of the runtime.