yoagent

ANTHROPIC_API_KEY=sk-... cargo run --example cli
GROQ_API_KEY=...        cargo run --example cli -- --provider groq --model openai/gpt-oss-120b
cargo run --example cli -- --api-url http://localhost:1234/v1 --model my-model   # LM Studio, llama.cpp, vLLM

Install

[dependencies]
yoagent = "0.27"
tokio = { version = "1", features = ["full"] }

Building for wasm32? Use default-features = false (see WebAssembly & Cloudflare Workers). On a native target keep the default native feature: without it reqwest has no TLS, and every HTTPS provider call fails at runtime.

Quick start

An agent that actually uses a tool — the thing the crate exists for:

use yoagent::provider::ModelConfig;
use yoagent::{tools, Agent, AgentEvent, StreamDelta};

#[tokio::main]
async fn main() {
    // The provider is selected from the config's protocol and the key is read
    // from ANTHROPIC_API_KEY. Call `.with_api_key(k)` to pass one explicitly.
    let mut agent = Agent::from_config(ModelConfig::claude_sonnet_5())
        .with_system_prompt("You are a coding assistant.")
        .with_tools(tools::default_tools());

    let mut events = agent.prompt("Find every TODO in src/ and summarise them").await;

    while let Some(event) = events.recv().await {
        match event {
            AgentEvent::MessageUpdate { delta: StreamDelta::Text { delta }, .. } => print!("{delta}"),
            AgentEvent::ToolExecutionStart { tool_name, .. } => println!("\n▶ {tool_name}"),
            AgentEvent::AgentEnd { .. } => break,
            _ => {}
        }
    }
    agent.finish().await;
}

Swap the model by swapping the config — the provider follows, and the key is read from that provider's conventional env var:

Agent::from_config(ModelConfig::groq("openai/gpt-oss-120b", "GPT-OSS 120B"));    // GROQ_API_KEY
Agent::from_config(ModelConfig::gemini_3_8_flash());                              // GEMINI_API_KEY
Agent::from_config(ModelConfig::ollama("http://localhost:11434/v1", "llama3.1:8b")); // no key

Why yoagent

Every agent runs the same loop, and almost every hand-written one gets the same things wrong: streams that end badly, tools that panic or hang, context that runs out, runs that never stop, spend nobody can account for. yoagent writes that loop once, with each guarantee pinned by a test, and keeps one rule for what goes in: does every agent need it, the same way? Anything else is an extension, a feature or a companion crate (design philosophy).

So it ships no vector stores, embedding pipelines, or task-graph layer — if your problem is retrieval or orchestration, one of these is the better fit:

What that focus bought:

• The loop is a free function. agent_loop() is stateless and takes everything it needs as arguments. Agent is an optional wrapper that adds history and queues. You can drive the loop yourself without adopting our state model.
• 7 native wire protocols, not one OpenAI-compat shim with adapters bolted on. Anthropic Messages, OpenAI Completions, OpenAI Responses, Azure, Gemini, Vertex, and Bedrock each have a real implementation, so provider-specific features (thinking budgets, prompt-cache breakpoints, reasoning deltas) survive instead of being flattened away.
• One plug-in contract for the whole run. An Extension can add tools, check input, allow, modify or deny each tool call, redact results, and check the final answer, with state that starts fresh each run. Install it as host policy and it governs every sub-agent too. Hooks that guard a call fail closed: a policy that cannot run denies, an input check rejects, a redaction that fails withholds.
• Steer a run that's already going. Inject guidance mid-flight; it's picked up between tool batches without restarting the turn.
• History is a tree, not a list. Session forks, checkpoints, and seeks. Edit an earlier turn and re-run it without destroying the original branch.
• Runs are recordable. With features = ["gasp"], a run becomes an append-only semantic event log in a git repo — restore is clone + replay. Conformance-checked in CI.
• The whole loop is testable offline. MockProvider scripts multi-turn tool-calling conversations and honours cancellation, so abort and steering paths are testable with no network or key.

Extend it

Everything that changes what the loop does goes through one contract, Extension: its run's RunHooks see on_input, before_model, before_tool, after_tool, on_stop, every event, and finish. A tool policy is a few lines:

use yoagent::extension::{ClonedHooks, RunHooks};
use yoagent::{ToolCallRequest, ToolDecision};

#[derive(Clone)]
struct NoForcePush;

#[async_trait::async_trait] // the `async-trait` crate
impl RunHooks for NoForcePush {
    async fn before_tool(&self, call: &ToolCallRequest<'_>) -> ToolDecision {
        let command = call.args["command"].as_str().unwrap_or_default();
        if command.contains("push --force") {
            ToolDecision::Deny("force-push is not allowed here".into())
        } else {
            ToolDecision::Allow
        }
    }
}

let agent = agent.with_extension(ClonedHooks::new("no-force-push", NoForcePush));

yoagent's own budget, tool gate and input guard are built the same way. Six runnable extension_* examples cover policies, redaction, verifiers, budgets, sub-agent policy and audit logs (guide).

Plugins and other ecosystems. yoagent-rutis turns rutis plugins — Rust, TypeScript (Node or Bun), Python or Go, loaded, reloaded and unloaded at runtime — into one Extension. Through small adapters it also runs many pi extensions and DeepSeek harness (DSH) tool plugins unchanged, with no change to yoagent's core: tools, tool policies, input checks, prompt additions and images cross over; commands and UI don't. An extension that hooks something the adapter can't enforce is refused, not half-run. How the 20 most-downloaded packages of each ecosystem fare (by monthly downloads, among npm's first 1000 search results per keyword), measured: plugin compatibility. Agents built this way — a coding agent with pi and DSH plugins in your browser, a handoff agent that asks without waiting and reports back — live in yobuild.

Runs where agents run

The same loop builds natively and for wasm32-unknown-unknown. In yoyo's Cloudflare Worker we measured about 4 ms to start and a median of ~45 ms of CPU per agent run — an agent spends most of a run waiting on the model, which Workers do not bill as CPU. A minimal Worker (one provider via Agent::from_provider, one tool, no decision model) is about 330 KiB gzipped. HTTP MCP works over the host's fetch; yoagent-workers turns the Workers AI binding into a decision model. See WebAssembly & Cloudflare Workers.

Built with yoagent

yoyo-evolve — a coding agent that evolves its own source in public. It began as 200 lines of Rust; every commit since has been agent-written and gated on tests. It runs on this loop with the openapi feature enabled.

Also built on yoagent:

Built something on yoagent? Open a PR and add it here — we'd like to see it.

What's in the box

Examples

Seventeen of the 22 runnable examples in examples/ are below; ten need no API key at all (eleven counting cli with a local model). The rest are live-provider harnesses and offline evaluation sweeps.

¹ --provider ollama or --api-url needs no key; hosted providers read their conventional env var.

² Scripted offline by default; -- --live uses DEEPSEEK_API_KEY or ANTHROPIC_API_KEY.

The companion crates have their own: language_plugins, pi_extensions and dsh_tools (TypeScript, Python, pi and DSH plugins) and a Clef tool-gate Worker.

Testing

MockProvider scripts a whole multi-turn tool-calling conversation with no network, and honours cancellation, so abort and steering paths are testable too. See Testing Your Agent; how the crate itself is tested and what CI runs is in CONTRIBUTING.

Documentation

• The book — concepts, guides, a page per provider, and the architecture and module map (source)
• Design philosophy — why yoagent is a loop library, the one extension contract, and what that costs
• API reference — built with all features enabled
• For coding agents: the yoagent skill — which feature for which job, tips and pitfalls, what changed per version (AgentSkills SKILL.md; also in the published crate) — and llms.txt, a map of every docs page
• CHANGELOG — every release
• CONTRIBUTING — how to build, test, and send a PR

MSRV is 1.86, enforced in CI. Raising it is a minor-version change.

Contributing

Bug reports, ideas and PRs are welcome — open an issue or pick one labelled help wanted. CONTRIBUTING covers building, the checks CI runs, and the PR checklist. Report security issues privately as described in SECURITY.

Acknowledgements

rutis, the plugin runtime behind yoagent-rutis, and the contributors who send fixes and ideas — including the ones who suggest them on X.

License

MIT — see LICENSE.