Noureddine RAMDI / yoagent: a minimal Rust AI agent runtime with multi-provider LLM support

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1199 Words
github-stars rust ai-agent llm tokio async event-driven

yologdev/yoagent

The complexity of AI agent frameworks often lies in the layers of planning, reflection, and retrieval-augmented generation (RAG) mechanisms they incorporate. But what if you stripped all that away and focused solely on the core loop of an agent: sending a prompt, streaming the LLM response, executing tools if requested, and looping until the task completes? That’s the approach behind yoagent, a Rust library that implements a deliberately minimal AI agent runtime centered on this simple cycle.

What yoagent does and how it works

yoagent is a Rust crate focused on implementing a minimal, event-driven AI agent loop. The fundamental cycle it runs is:

  • Prompt the LLM with a query or instruction.
  • Stream the LLM’s response incrementally.
  • Detect if the response calls for a tool execution.
  • Execute the tool(s).
  • Loop back to the LLM prompt with updated context if necessary.
  • Finish when no further tools or prompts are needed.

This minimalism is intentional, rejecting the common trend of embedding complex planning, reflection, or RAG layers inside the agent runtime. Instead, yoagent bets on a clean, observable event-driven design where each phase of the loop emits events, enabling easy inspection and extension.

Under the hood, the architecture supports 7 API protocols covering more than 20 LLM providers. It uses a modular registry design, with one OpenAI-compatible implementation handling most providers via per-provider quirk flags. This lets the library interface with multiple LLM backends through a unified API while accommodating provider-specific oddities.

Built-in tools cover common needs out of the box. These include:

  • Bash command execution.
  • File input/output.
  • Surgical text editing.
  • Directory listing.
  • Ripgrep-powered search.

More advanced features include the ability to execute tools in parallel, spawn sub-agents through a dedicated SubAgentTool, detect and compact context overflow with multiple tiers, and auto-generate OpenAPI tools. It also supports integration with AgentSkills, a skill-loading framework compatible across multiple agent engines, and MCP (Multi-Channel Protocol) for integration with various messaging platforms.

The repo ships with a ~250-line interactive CLI example dubbed a ‘baby Claude Code’ that demonstrates the full breadth of the library’s capabilities in a compact, hands-on form.

Technical strengths and design tradeoffs

The distinguishing technical strength of yoagent is its disciplined minimalism. By focusing on a simple Prompt → Stream → Tool → Loop cycle, the codebase remains compact and easier to reason about. This contrasts with many AI agent frameworks that incorporate layers of planning algorithms, reflection mechanisms, or complex memory retrieval systems, which can obscure the core logic and increase maintenance burden.

The event-driven architecture means all stages in the agent loop emit well-defined events. This makes the runtime highly observable and extensible. You can hook into these events for logging, debugging, or custom behavior without altering the core library.

Supporting a broad range of LLM providers through a modular registry is another technical highlight. Having a single OpenAI-compatible implementation handle most providers via quirks flags reduces duplication and eases maintenance. It means adding or updating providers is centralized.

The built-in tools cover a practical set of operations for most AI agent use cases — command execution, file manipulation, text editing, directory operations, and search. The ability to run tools in parallel is a nice touch for efficiency when multiple independent actions are triggered.

Sub-agent support via SubAgentTool introduces a hierarchical agent model. You can spawn task-specific sub-agents that run independently but feed results back to the main agent. This enhances modularity and can help manage complex workflows.

The tradeoff with yoagent’s approach is that it deliberately avoids over-engineered features like RAG or internal planning. While this keeps the runtime lean, it means you may need to implement your own external memory or planning layers if needed. It’s a design choice favoring simplicity and transparency over out-of-the-box autonomy.

The codebase, written in Rust, benefits from Rust’s async ecosystem through Tokio for concurrency and streaming. The library is relatively small, making it suitable for embedding inside larger Rust projects where agent functionality is one component.

Quick start

Installation is straightforward for Rust projects. You can add yoagent and Tokio with the full feature set via Cargo:

cargo add yoagent tokio --features tokio/full

Or add this to your Cargo.toml dependencies:

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

Here is a minimal example demonstrating how to create an agent using the AnthropicProvider, set a system prompt, and stream the response events:

use yoagent::agent::Agent;
use yoagent::provider::AnthropicProvider;
use yoagent::types::*;

#[tokio::main]
async fn main() {
    let mut agent = Agent::new(AnthropicProvider)
        .with_system_prompt("You are a helpful assistant.")
        .with_model("claude-sonnet-4-20250514")
        .with_api_key(std::env::var("ANTHROPIC_API_KEY").unwrap());

    let mut rx = agent.prompt("What is Rust's ownership model?").await;

    while let Some(event) = rx.recv().await {
        match event {
            AgentEvent::MessageUpdate {
                delta: StreamDelta::Text { delta }, ..
            } => print!("{}", delta),
            AgentEvent::AgentEnd { .. } => break,
            _ => {}
        }
    }
}

This example shows the async streaming of partial outputs, allowing real-time consumption of the LLM’s response.

yoagent also supports loading domain-specific skills compatible with the AgentSkills format. Skills are directories with a SKILL.md file and optional scripts. These skills provide modular domain expertise that the agent can invoke dynamically. The library handles injecting the skills index into the system prompt and reading skill instructions on demand via tools, without any special infrastructure.

verdict

yoagent is a well-crafted Rust library for developers who want a minimal, transparent AI agent runtime without the complexity of embedded planning or retrieval systems. Its event-driven architecture and multi-provider support make it flexible and extensible for real-world usage.

The tradeoff is its simplicity: if your use case demands autonomous planning, rich memory, or integrated RAG, you will need to build those layers externally or look elsewhere. But for Rust projects requiring a clean agent loop with built-in tools and the ability to handle multiple LLM providers, yoagent is a strong foundation.

Its clear codebase and practical design also make it a good learning resource for anyone looking to understand how to implement AI agents in Rust with async streaming and modular tool execution. The included CLI example offers a compact, interactive playground to experiment with its features.

In sum, yoagent bets on less to achieve more: a lean runtime, observable event flow, and extensibility through skills and sub-agents. It’s worth exploring if you want to embed AI agents in Rust without the overhead of heavyweight agent frameworks.

→ GitHub Repo: yologdev/yoagent ⭐ 162 · Rust