TinyAgents
TinyAgents is a small, provider-neutral agent harness for Rust. It takes its
shape from LangChain (models, tools, middleware,
structured output, streaming, usage/cost) — rebuilt as ordinary, typed Rust
with no hidden magic.
It is for Rust services that need to call models and tools in a loop, want
that loop to be resumable and inspectable, and would rather not carry a
Python runtime or a framework's DSL to get there.
What's inside
TinyAgents is a Cargo workspace, not one crate. Depend on the pieces you need:
tinyagents-harness — provider-neutral model calls, typed tools,
middleware, structured output, streaming, usage/cost accounting, retries,
caching, and a Claude Code CLI model adapter with stream-json,
session, authentication, and MCP endpoint support. Features: sqlite,
storage-drivers, multimodal, png-optimize (opt-in PNG re-compression), media,
claude-code and langfuse (both default), json-schema (opt-in JsonSchema for context config types), and tracing (forwards to tinytools-agent/tracing for its parsing diagnostics; the harness's own instrumentation is always compiled in).
tinyagents-harness-tools — reusable implementations for the harness:
goals and budgets, per-thread todos, skill tool packs, subagent control
tools, time and clarification tools, plan exit, per-call binding, and
per-thread locks. Features: todos, goals, skills (all default), and
subagents (opt-in). See the crate guide.
tinyagents-tasks — detached-task machinery: task
model, TaskStore (in-memory and JSONL), DetachedTaskRegistry, restart
reconciliation, the durable completion router (push a finished child to its
parent, redelivered after a restart), and the spawn/await/cancel/steer
orchestration tools.
tinyagents-registry — a named capability catalog (models, tools,
agents, and routers), plus an offline model price/capability catalog.
tinyagents-session — a SQLite-backed store for session history,
messages, tool calls, cost, and run lineage, plus JSONL transcripts and the
threads chat thread/message store. Transcript spend separates charged and
estimated costs from unknown or legacy usage; see the
cost provenance contract.
tinyagents-definition — the host-owned agent definition vocabulary:
identity, description, declared model/tools/delegates, and a read-only
catalogue seam. Authorization, prompt construction, and execution stay with
the host and harness.
tinyagents-runtime — host-neutral stateful turns over the harness and
append-only transcript seam; hosts retain policy, prompt composition,
authorization, and durable-dialect conversion.
tinyagents-live — live (realtime voice) agent sessions: declares a
harness's tools to a tinyliveagents
provider (Gemini Live, ElevenLabs Agents, Sarvam) and runs every tool call
the model makes through the harness's own admission and middleware
pipeline, so host policy applies to spoken requests too.
tinyagents-orchestration — host-neutral composition of durable
multi-agent work (teams and workflows) over the graph, harness, and session
layers; depends one-way on those crates and stays host-free.
tinyagents-integration-tests — cross-crate tests and the runnable
examples referenced below (not published, workspace-internal).
Quick start
None of the crates are published to crates.io (publish = false in every
Cargo.toml), so add them as git or path dependencies:
[dependencies]
tinyagents-harness = { git = "https://github.com/tinyhumansai/tinyagents", package = "tinyagents-harness" }
tinyagents-registry = { git = "https://github.com/tinyhumansai/tinyagents", package = "tinyagents-registry" }
# The code samples below build `Message` and provider types directly from
# TinyInference, the message/model crate TinyAgents is built on. It is a
# separate git dependency, not re-exported by the crates above.
tinyinference-llm = { git = "https://github.com/tinyhumansai/tinyinference", package = "tinyinference-llm" }
A one-shot model call through the harness (export OPENAI_API_KEY=... then
cargo run -p tinyagents-integration-tests --example openai_chat):
use std::sync::Arc;
use tinyagents_harness::runtime::AgentHarness;
use tinyinference_llm::message::Message;
use tinyinference_llm::providers::openai::OpenAiModel;
let model = OpenAiModel::from_env()?;
let mut harness: AgentHarness<()> = AgentHarness::new();
harness.with_model_resolver(Arc::new(tinyagents_harness::host::FixedModelResolver::named(
"openai",
Arc::new(model),
)));
let run = harness
.invoke_default(&(), vec![Message::user("What is a Rust trait?")])
.await?;
println!("{}", run.text().unwrap_or_default());
Harness
tinyagents-harness runs the model/tool agent loop: provider-neutral model
calls, typed tool definitions, middleware, structured output, streaming,
usage and cost accounting, retries and limits, response caching, and a testkit
for exercising the loop without a live provider. Memory, workspace lifecycle,
authorization, and persistence policy stay in the host and can wrap a complete
run with AgentMiddleware.
Tool packs keep read-only disclosure available in mixed-permission sessions
while gating each bound invocation on its actual arguments. The harness also
exposes executor-entry observation
for finish checks and host bookkeeping: it reports the bound target without
changing the outer transcript or treating a preview as a write.
Subagent orchestration
tinyagents-orchestration owns child-agent composition and the shared
tinyagents_orchestration::subagent::SubAgentJobRegistry. The subagents
feature in tinyagents-harness-tools
exposes tinyagents_harness_tools::subagents, which provides
DriverSubAgentTool, the host-planned typed dispatcher. Every call starts an
asynchronous job and returns its stable job id; SubAgentJobsTool provides
status, wait, cancellation, and steering over the shared registry, while
SubAgentMessageTool delivers messages. SubagentDriver coordinates durable
lifecycle preparation, execution, pause, resume, and persistence. Teams and
workflow DAGs are intentionally outside this focused crate.
Session runtime
tinyagents-runtime owns mutable model history for one host-owned
conversation, a stable prompt prefix, a frozen tool declaration snapshot, and
the sequencing around one append-only transcript commit. A host supplies the
driver, its lossless transcript codec, and lifecycle hooks. On a driver error,
the runtime can commit recoverable logical history with an interrupted,
display-only partial in the same history operation; model-context replay omits
that partial. A codec can also derive TurnUsage from its explicit host
context after the driver runs; that usage is attached to the same atomic
append's final assistant row for both success and recoverable partials. A
post-commit hook observes durable successes but cannot change their result.
See the runtime module.
Registry
tinyagents-registry is a name-addressable catalog of models, tools, agents,
graphs, and routers. Application code resolves capabilities by name against it
rather than holding direct handles.
Providers
Every provider speaks the OpenAI Chat Completions wire format, so one adapter
reaches all of them; only the base URL and model differ. Built-in presets:
OpenAI, Anthropic (via its OpenAI-compatible endpoint), DeepSeek, Groq, xAI,
OpenRouter, Together, Mistral, and Ollama (local). Any other OpenAI-compatible
endpoint works by base URL — see providers.env.example
for the full list and configuration format.
Examples
All live in
crates/tinyagents-integration-tests/examples/:
basic_graph, complex_graph, durable_graph,
resilient_graph — a minimal typed graph, then conditional
routing/fanout, checkpoint/resume/time-travel, and node-level retry.
agent_loop_tools — the agent/tool loop the harness runs.
orchestrator_subagents — an orchestrator agent that resolves and calls
sub-agents by name from the registry.
goals_and_todos — a durable goal driving a todo checklist on one
thread.
openai_chat, openai_tools, openai_structured,
openai_graph_agent — provider-backed chat, tool calling, structured
output, and a graph-driven agent (all need OPENAI_API_KEY).
subconscious_loop — an offline, testable autonomous closed-loop
harness (see the source and test in
crates/tinyagents-integration-tests/examples/subconscious_loop/).
Documentation
docs/spec/README.md — architecture specification.
- Wiki — Harness, Graph
Runtime, Registry, Providers, Quick Start,
Examples, Development.
Development
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo build --workspace --all-targets
cargo test --workspace
Verifying real providers (BYOK)
cargo test never touches the network. To check the providers you hold keys
for — a chat call, a streaming call, and a tool call each, reported as a
provider | PASS/FAIL(reason) | latency(ms) table:
cp providers.env.example providers.env # fill in the keys you have; blank => skipped
PROVIDER_MATRIX=1 cargo test -p tinyagents-integration-tests --test live_provider_matrix -- --nocapture
Dialling is opt-in through PROVIDER_MATRIX=1, so a bare cargo test stays
offline even with a fully configured providers.env. providers.env is
gitignored — never commit real keys.
Contributing
Read CONTRIBUTING.md before opening a pull request.
License
TinyAgents is licensed under GPL-3.0-only.
Harness correction producers can use context-bound
EphemeralInstructionQueue
for one-shot model request instructions without persisting them in history.
The harness provides after-model stop hooks:
hosts supply budget/goal policy and accounting; the library owns ordered
observation, per-run state and pause delivery.
tinyagents-runtime::transcript supplies mechanical execution projections
for native tool rounds, ordered media references and reasoning replay. Hosts
retain their lossless durable codecs and legacy marker policy.
tinyagents-runtime::turn_driver is the generic turn loop for a session:
a TurnDriver assembles one harness per turn from a host TurnPlan and applies
per-turn TurnControls (model-call cap and pause-at-cap, early-exit tools,
deferred completion, delegated-child scope, run-queue steering). See its
README.