TinyAgents

RustAgents is a Rust-native framework for building LLM agents as typed, inspectable workflows.

The project starts from a simple belief: agent systems should not be piles of callbacks and hidden loops. They should be explicit programs with state, edges, policies, tools, model calls, checkpoints, and events that you can read, test, debug, serialize, and run again.

RustAgents brings that shape to Rust. It combines strongly typed application state, async model and tool traits, executable graph primitives, and a roadmap for declarative agent workflow languages that LLMs can safely author, inspect, compile, and run.

Why TinyAgents

Python and TypeScript have mature agent frameworks. Rust developers deserve the same level of orchestration power without giving up Rust's clarity, type system, performance, and production discipline.

RustAgents is designed for teams that want to build real agent products:

typed state instead of unstructured runtime bags
explicit graph execution instead of implicit control flow
model and tool traits that are easy to test
deterministic routing around nondeterministic LLM calls
observable runs with room for streaming, checkpoints, interrupts, and replay
declarative workflow definitions that can be reviewed before execution
parallel agents, sub-agent fanout, context forking, and blocking child agents as first-class workflow concepts

The long-term goal is not just "call an LLM from Rust." The goal is to make Rust a serious home for durable agent runtimes.

The Big Idea: Declarative Workflows For LLMs

LLMs are good at proposing plans, but raw generated code is a dangerous execution boundary. RustAgents is moving toward a safer path: an expressive, declarative workflow language for graph blueprints.

A .rag workflow should describe what an agent system is allowed to do:

which models, tools, stores, and sub-agents are available
which nodes exist
how state flows between nodes
when work fans out in parallel
how child agents join back into parent state
which agents are blocking, optional, racing, or quorum-based
where checkpoints, interrupts, retries, budgets, and policies apply

That means an LLM can create or modify a workflow without receiving arbitrary host-code execution. The generated plan becomes source, the source becomes an AST, the AST is validated against registries and policy, and only then does it compile into the same graph runtime that hand-written Rust uses.

Conceptually:

graph research_review {
  start supervisor

  channel messages messages
  channel findings append
  channel critiques append

  node supervisor {
    kind agent
    model "default"
    tools ["search", "read_repo"]

    send [
      research_agent { question: input.question },
      verifier_agent { question: input.question }
    ]

    join review
  }

  node review {
    kind sub_agent
    agent "final_reviewer"
    blocking true
    next END
  }
}

This is the power RustAgents is built around: agents can author workflows that spawn other agents, run branches in parallel, call blocking reviewers, fork context safely, and merge outputs through typed reducers while the runtime keeps policy and observability intact.

Current Status

RustAgents is early. The crate currently provides the foundation:

chat message primitives
async chat model and tool traits
executable state graphs with direct and conditional routing
graph validation, recursion limits, visited-node traces, and examples
extensive architecture docs for the harness, graph runtime, registry, expressive language, and REPL language

The docs describe the target system in more detail than the current crate implements. That is intentional: the public repository is both a working Rust library and an open design space for the agent runtime Rust should have.

Install

Until the crate is published, use the repository directly:

[dependencies]
rustagents = { git = "https://github.com/tinyhumansai/rustagents" }

For local development:

[dependencies]
rustagents = { path = "." }

Quick Example

use rustagents::{ChatMessage, Node, NodeOutput, Result, StateGraph};

#[derive(Clone, Debug)]
struct AgentState {
    messages: Vec<ChatMessage>,
    needs_tool: bool,
}

#[tokio::main]
async fn main() -> Result<()> {
    let graph = StateGraph::new()
        .add_node(Node::new("agent", |mut state: AgentState| async move {
            state.messages.push(ChatMessage::assistant("I should use a tool."));

            if state.needs_tool {
                Ok(NodeOutput::route(state, "tool"))
            } else {
                Ok(NodeOutput::end(state))
            }
        }))
        .add_node(Node::new("tool", |mut state: AgentState| async move {
            state.messages.push(ChatMessage::tool("echo", "tool result"));
            state.needs_tool = false;
            Ok(NodeOutput::continue_with(state))
        }))
        .set_start("agent")
        .add_conditional_edges("agent", [("tool", "tool")])
        .add_edge("tool", "agent");

    let run = graph
        .run(AgentState {
            messages: vec![ChatMessage::user("Can you use a tool?")],
            needs_tool: true,
        })
        .await?;

    println!("{:#?}", run.visited);
    Ok(())
}

Run the bundled example:

cargo run --example basic_graph

Architecture

RustAgents is organized around five major surfaces:

Harness: provider-neutral models, tools, middleware, prompts, context, memory, streaming, observability, retries, caching, and test doubles.
Graph runtime: typed state graphs, nodes, routing, reducers, commands, parallel execution, checkpointing, interrupts, subgraphs, and sub-agents.
Registry: named models, tools, agents, graphs, stores, middleware, and policies that declarative workflows can bind to safely.
Expressive language: .rag graph blueprints that are readable by humans, authorable by agents, and compiled through the same validation path.
REPL language: .ragsh interactive orchestration for inspecting, scripting, and controlling harness and graph runs through registered capabilities.

Start with the system specification:

Development

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo build --all-targets
cargo test

Run the example:

cargo run --example basic_graph

Contributing

RustAgents is open source and welcomes focused contributions. The highest-value work right now is small, well-tested improvements to the core graph API, harness traits, docs, examples, and the declarative language design.

Read CONTRIBUTING.md before opening a pull request.

License

RustAgents is licensed under GPL-3.0-only.

Built by TinyHumans for the Rust agent ecosystem.

tinyagents 0.1.0