Architecture

Architecture

TinyAgents combines ideas from LangChain, LangGraph, and Rust-native typed API design. The goal is not to clone a Python framework; it is to make durable agent systems fit naturally in Rust.

Layered Model

flowchart TD
    App[Application Code]
    App --> Graph[Graph Runtime]
    App --> Harness[Agent Harness]
    Graph --> Harness
    Harness --> Providers[Provider Adapters]
    Harness --> Tools[Typed Tools]
    Harness --> Middleware[Middleware]
    Harness --> Events[Events, Usage, Cost]
    Registry[Registry] --> Graph
    Registry --> Harness
    Rag[.rag Source] --> Compiler[Parser and Compiler]
    Compiler --> Registry
    Compiler --> Graph
    Ragsh[.ragsh REPL] --> Registry

Loading

Harness

The harness owns nondeterministic agent work:

• model request construction
• provider adapter calls
• tool registration and execution
• middleware hooks
• structured output strategy
• streaming deltas
• provider error normalization
• usage and cost records
• retries, limits, and cancellation
• deterministic model and tool test doubles

The graph can call the harness, but provider details stay outside graph execution.

Graph Runtime

The graph owns deterministic state movement:

• typed state and updates
• reducers
• nodes
• static and conditional edges
• commands
• checkpoints
• interrupts
• topology export
• run status

Graph execution should be understandable from topology, state, routes, checkpoints, and emitted events.

Registry

The registry owns named capabilities. It lets Rust code, .rag blueprints, and REPL sessions refer to capabilities by stable names instead of directly reaching into process globals.

Registry entries can describe:

• models
• tools
• agents
• graphs
• stores
• middleware
• policies

This makes generated or user-authored workflow source bindable and auditable before execution.

Expressive Language

.rag is the planned workflow source format for graph blueprints. It should be safe for humans and models to author because it describes capabilities and topology instead of arbitrary host code.

The expected flow is:

flowchart LR
    Source[.rag source] --> Parse[Parse]
    Parse --> Compile[Compile blueprint]
    Compile --> Bind[Bind registry capabilities]
    Bind --> Graph[Compiled graph]
    Graph --> Run[Execute]

Loading

REPL Language

.ragsh is the planned interactive control surface for registered harness and graph capabilities. It is meant for inspection, scripting, debugging, and controlled run management.

Design Rule

Each layer should keep its contract narrow:

• the harness calls providers and tools
• the graph moves typed state through explicit topology
• the registry binds names to capabilities
• .rag describes workflow source
• .ragsh controls registered capabilities interactively

No layer should bypass another layer's policy, observability, or validation boundary.