Expand description
§TinyAgents — a durable agent + graph 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: rather than stuffing everything into one context window, a model treats long context as an external environment it decomposes, recursively calling sub-models, sub-agents, and sub-graphs as functions. TinyAgents brings that to Rust as a production-shaped harness (capability calls by name, depth tracking, and trajectory/event logging). The scripted form of that loop — an embedded interpreter running model-written code cells — is a host concern built on these surfaces, not something this crate ships.
§The four surfaces
- 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. - 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 durableThreadGoalwith graph-native continuation and aTaskBoardkanban — exposed as harness tools. - Registry (
registry) — a named capability catalog (models, tools, agents, graphs, stores, middleware, policy) that.ragbinds by name. - 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.
§The recursion story
.rag lowers 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. Two Cargo features gate optional,
heavier dependencies instead: sqlite (embedded SQLite checkpointer,
[graph::checkpoint::SqliteCheckpointer]) and tools (the builtin generic
tool family, [harness::tools]).
Scripted, imperative orchestration surfaces (an embedded interpreter driving
capability calls — the .ragsh REPL and the recursive-language-model
runtime that used to ship here) are deliberately not part of this crate:
they are host concerns, built on top of registry and harness.
§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::run_queue::QueueLane;pub use harness::run_queue::QueueStatus;pub use harness::run_queue::RunQueue;pub use harness::cancel::CancellationToken;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::CancelledDetachedTask;pub use graph::DetachedTaskRegistry;pub use graph::DetachedTaskRegistryError;pub use graph::DetachedTaskSnapshot;pub use graph::DetachedTaskWaitOutcome;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::parallel::ClaimConflict;pub use graph::parallel::ClaimPathError;pub use graph::parallel::DispatchMode;pub use graph::parallel::DispatchPlan;pub use graph::parallel::WorkspaceClaim;pub use graph::parallel::parse_relative_claim_paths;pub use graph::parallel::paths_overlap;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
Resultalias. - 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.