Quick Start

Quick Start

The shortest path from zero to a running TinyAgents graph, plus the crate layout you will navigate as you go deeper.

Add the crates

There is no tinyagents facade crate — every crate in the workspace has publish = false, so none of them are on crates.io. Add the crates you need as git or path dependencies. For example, as a git dependency pinned to a commit or branch:

[dependencies]
tinyagents-harness = { git = "https://github.com/tinyhumansai/tinyagents", package = "tinyagents-harness" }
tinyagents-graph = { git = "https://github.com/tinyhumansai/tinyagents", package = "tinyagents-graph" }

Or, working inside a checkout of this repository, as a path dependency (this is how tinyagents-integration-tests/Cargo.toml depends on the other workspace crates):

[dependencies]
tinyagents-harness = { path = "../tinyagents-harness" }
tinyagents-graph = { path = "../tinyagents-graph" }

Add only the crates your project actually uses:

• tinyagents-harness — model calls, tools, middleware, streaming.
• tinyagents-graph — the durable state-graph runtime.
• tinyagents-language — the .rag blueprint format.
• tinyagents-registry — the named capability catalog.
• tinyagents-session — durable session history.

The OpenAI-compatible provider (tinyinference::providers::openai::OpenAiModel, a dependency of tinyagents-harness) is compiled in by default, and the build stays offline unless you actually make a call.

Optional features

Each crate gates its own optional backends:

• tinyagents-harness: sqlite (the SQLite-backed response cache), tools (the built-in tool implementations), multimodal (image/data-URI handling), tracing.
• tinyagents-graph: sqlite (SqliteCheckpointer), tracing.
• tinyagents-registry and tinyagents-session: tracing only.
• tinyagents-language: no optional features.

Tracing instrumentation compiles to a no-op unless the tracing feature is enabled on the crate you're using. Enable what you need:

tinyagents-graph = { path = "../tinyagents-graph", features = ["sqlite"] }

To use a hosted model, export your key (and optionally point at a different model or base URL):

export OPENAI_API_KEY=...
export OPENAI_MODEL=gpt-4.1-mini          # optional
export OPENAI_BASE_URL=https://api.openai.com/v1   # optional

The same OpenAiModel adapter reaches other providers (Anthropic, Ollama, DeepSeek, Groq, xAI, OpenRouter, Together, Mistral, and other OpenAI-compatible endpoints) through named constructors. See Providers.

Clone, test, and run

To work against the source or run the bundled examples, clone the canonical repository:

git clone https://github.com/tinyhumansai/tinyagents.git
cd tinyagents
cargo test --workspace

Useful local checks (these mirror CI):

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

Run the local graph example

The basic graph example needs no provider credentials and runs fully offline:

cargo run -p tinyagents-integration-tests --example basic_graph

It threads typed Rust state through a small two-node graph, routes conditionally after the agent node, and exits when the state no longer needs the tool:

flowchart TD
    Start((START)) --> Agent[agent]
    Agent -->|needs_tool| Tool[tool]
    Tool --> Agent
    Agent -->|done| End((END))

Loading

Run an OpenAI-backed example

OpenAI-backed examples need OPENAI_API_KEY:

export OPENAI_API_KEY=...
cargo run -p tinyagents-integration-tests --example openai_chat

Other offline examples include complex_graph, durable_graph, resilient_graph, agent_loop_tools, rag_blueprint, goals_and_todos, and subconscious_loop; hosted examples include openai_tools, openai_structured, openai_graph_agent, orchestrator_subagents, and openai_self_blueprint. See Examples.

Crate layout

TinyAgents is organized as a virtual Cargo workspace with crates/* members and no facade crate. Knowing where each piece lives makes the source easy to navigate:

• crates/tinyagents-harness/ — provider-neutral model calls, typed tools, middleware, structured output, streaming, usage/cost, retry/limits, cache, memory/embeddings, sub-agents, steering, summarization, and testkit doubles.
• crates/tinyagents-graph/ — durable typed state graphs with START/END, nodes, edges, conditional routing, commands, Send fanout, reducers/channels, checkpoints, interrupts, subgraphs, and topology export.
• crates/tinyagents-registry/ — the named capability catalog (models, tools, agents, graphs, routers, reducers) that .rag binds by name.
• crates/tinyagents-language/ — the declarative .rag blueprint language (lexer → parser → compiler).
• crates/tinyagents-session/ — durable SQLite-backed session history and run ledger.
• crates/tinyagents-tracing/ — shared, feature-gated tracing macros.
• crates/tinyagents-integration-tests/ — cross-crate tests (tests/) and runnable examples (examples/); not a library dependency.

Supporting paths:

• docs/spec/ — contributor-facing system specification.
• wiki/ — this GitHub wiki source.

Next steps

• Examples — work through the runnable examples, including the .rag blueprint demos.
• Architecture — how the crates compose end to end.
• Harness and Graph Runtime — the two crates most applications start with.