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-tasks — detached-task stores, registry, completion router and orchestrate_* tools (re-exported as tinyagents_graph::orchestration).
• tinyagents-orchestration — subagents, teams and workflows.
• tinyagents-registry — the named capability catalog.
• tinyagents-session — durable session history.
• tinyagents-runtime — host-neutral stateful sessions over the harness.
• tinyagents-definition — the host-owned agent definition vocabulary.
• tinyagents-live — live (realtime voice) agent sessions.

The OpenAI-compatible provider (tinyinference_llm::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), png-optimize, media, storage-drivers, tracing. claude-code and langfuse are on by default.
• tinyagents-graph: sqlite (SqliteCheckpointer), storage-drivers, tracing.
• tinyagents-session: storage-drivers, tracing.
• tinyagents-registry and tinyagents-orchestration: tracing only.
• tinyagents-tasks, -runtime, -definition, -live: no optional features.

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, goals_and_todos, and subconscious_loop; hosted examples include openai_tools, openai_structured, and openai_graph_agent. orchestrator_subagents lives in the tinyagents-orchestration package (cargo run -p tinyagents-orchestration --example orchestrator_subagents). 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-definition/ — the host-owned agent definition vocabulary (identity, declared model/tools/delegates, a read-only catalogue seam).
• crates/tinyagents-harness/ — provider-neutral model calls, typed tools, middleware, structured output, streaming, usage/cost, retry/limits/failover, cache, steering, summarization, typed terminal outcomes, and testkit doubles.
• crates/tinyagents-tasks/ — graph-independent detached-task machinery: task stores, DetachedTaskRegistry, restart reconciliation, the durable completion router, and the orchestrate_* tools.
• 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. tinyagents_graph::orchestration re-exports tinyagents-tasks.
• crates/tinyagents-registry/ — the named capability catalog (models, tools, agents, graphs, routers, reducers) and the offline model catalog.
• crates/tinyagents-session/ — durable SQLite-backed session history and run ledger.
• crates/tinyagents-runtime/ — host-neutral stateful sessions over the harness and transcript storage.
• crates/tinyagents-orchestration/ — subagent invocation and lifecycle (SubagentDriver), teams and workflows.
• crates/tinyagents-live/ — live (realtime voice) agent sessions.
• 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.
• Architecture — how the crates compose end to end.
• Harness and Graph Runtime — the two crates most applications start with.