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

                              author / inspect
                         +------------------------+
                         | .rag workflow source   |
                         | .ragsh REPL commands   |
                         +-----------+------------+
                                     |
                                     v
                         +------------------------+
                         | Parser and compiler    |
                         | syntax -> blueprint    |
                         +-----------+------------+
                                     |
                                     v
+----------------+       +------------------------+       +----------------+
| Application    |------>| Capability Registry    |<------| Model Catalog  |
| Rust builders  |       | names -> capabilities  |       | prices/profile |
+-------+--------+       +-----------+------------+       +----------------+
        |                            |
        |                            v
        |                +------------------------+
        +--------------->| Graph Runtime          |
                         | state | reducers       |
                         | nodes | routes | runs  |
                         +-----------+------------+
                                     |
                                     v
                         +------------------------+
                         | Agent Harness          |
                         | prompts | context      |
                         | tools | middleware     |
                         | events | usage | retry |
                         +-----+------------+-----+
                               |            |
                               v            v
                    +----------------+  +----------------+
                    | Provider       |  | Tool Registry  |
                    | Adapters       |  | typed schemas  |
                    +-------+--------+  +-------+--------+
                            |                   |
                            v                   v
                    +----------------+  +----------------+
                    | OpenAI         |  | Local systems  |
                    | Anthropic      |  | APIs, stores   |
                    | Ollama, etc.   |  | side effects   |
                    +----------------+  +----------------+

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:

.rag source
    |
    v
parse source
    |
    v
compile blueprint
    |
    v
bind registry capabilities
    |
    v
compiled graph
    |
    v
execute run

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.