Agent Rs

agent-rs

A pure-Rust async runtime for shipping LLM agents.

Multi-provider · tool-capable end-to-end · structured permissions · real MCP · zero unsafe.

[](https://github.com/ZSeven-W/agent-rs/actions) [](#testing) [](https://www.rust-lang.org) [](https://github.com/ZSeven-W/agent-rs/blob/main/crates/agent/src/lib.rs) [](./LICENSE)

Languages: [English](./README.md) · [简体中文](./docs/readme/README.zh.md) · [繁體中文](./docs/readme/README.zh-TW.md) · [日本語](./docs/readme/README.ja.md) · [한국어](./docs/readme/README.ko.md) · [Français](./docs/readme/README.fr.md) · [Español](./docs/readme/README.es.md) · [Deutsch](./docs/readme/README.de.md) · [Português](./docs/readme/README.pt.md) · [Русский](./docs/readme/README.ru.md) · [हिन्दी](./docs/readme/README.hi.md) · [Türkçe](./docs/readme/README.tr.md) · [ไทย](./docs/readme/README.th.md) · [Tiếng Việt](./docs/readme/README.vi.md) · [Bahasa Indonesia](./docs/readme/README.id.md)

┌─ user ──┐    ┌─── QueryLoop ───────────────────────────────────────┐
│ prompt  │───▶│ Streaming → ToolDispatch → ToolCollecting → Yield │──▶ Event::*
└─────────┘    │       ↑                                       │     │
               │       └──── auto-compact / hooks / cost ◀─────┘     │
               └─────────────────────────────────────────────────────┘
                  │            │            │            │
                  ▼            ▼            ▼            ▼
              Anthropic    OpenAI-*       Ollama         MCP servers
              (SSE)        (compat)       (local)        (stdio / HTTP)

---

TL;DR

use agent::prelude::*;
use std::sync::Arc;

let provider = Arc::new(AnthropicProvider::new(std::env::var("ANTHROPIC_API_KEY")?));
let engine = QueryEngine::new(provider, "claude-opus-4-7").with_system("Be concise.");

let mut stream = engine.run("Summarize Rust's borrow checker in two lines.", AbortController::new()).await?;
while let Some(event) = futures::StreamExt::next(&mut stream).await {
    if let Event::TextDelta { delta } = event? { print!("{delta}") }
}

That's a complete agent — provider streaming, tool dispatch, hooks, permissions, auto-compaction, USD cost tracking — all wired up. Drop in Files API attachments, MCP servers, or the bundled coding tool pack with one extra line each.

---

ZSeven-W Products

agent-rs is part of the ZSeven-W AI-native product family:

• zode - an AI-native coding CLI for terminal workflows, built around a Rust microkernel, plugins, multi-provider models, and a full-screen TUI.
• jian - a Rust-native cross-platform UI framework where an .op file can be an app.
• noema - local-first, non-vector memory for coding agents, including review queues, lexical recall, MCP, S3 offload, and enterprise policy controls.
• OpenPencil - an open-source AI-native vector design tool for design-as-code workflows and concurrent Agent Teams.

---

Why agent-rs?

• 🦀 Rust-native, library-only. No tokio::main hijack, no global state, no panic! on bad input. #![forbid(unsafe_code)] in every crate. Drop it into a CLI, an IDE plugin, a desktop app, or a server — the runtime doesn't care.
• 🔌 Three providers, one event vocabulary. Anthropic Messages (hand-rolled SSE — full prompt-cache + extended-thinking betas, no SDK dep), async-openai 0.36 (DeepSeek / Moonshot / Groq / OpenRouter / LM Studio), and local Ollama. Stream Event::TextDelta, ToolUse, Usage, Result — same shape from every backend.
• 🛠 Tool-capable end-to-end. Define a tool, register it, the runtime wires the JSON Schema into the request body, dispatches ToolUse events to your code, feeds results back. Multi-turn loop with a phase machine. Receipt-order concurrent execution. Permissions and cost tracking are wired through, not bolted on.
• 🛡 Structured permissions that fail safe. A 7-step decision chain (deny / ask / callback / bypass / allow / default-ask / dont_ask), composable PermissionMatcher rules over tool input shapes (JSON-pointer fields, glob/prefix/regex patterns, AnyOf / AllOf / Not), and a 4-level SafetyClass lattice where Unknown ≡ Destructive for gating — so unclassified tools never slip through.
• 🔗 MCP that actually plugs in. Full Model Context Protocol client lifecycle: stdio child processes, streamable HTTP, OAuth 2.0 + PKCE, server-initiated elicitation, channel permissions, stale-handle reconnect repair. Tool calls don't serialize on a mutex. close() doesn't deadlock during slow RPCs.
• 💸 Cost accounting in nanodollar precision. Event::Usage flows into a CostTracker with a model-price catalog (Anthropic + GPT defaults, BYO entries trivially). u128 integer accumulator — no f64 drift across long sessions.
• 📎 Files API for big attachments. FilesClient trait + AnthropicFilesClient. Smart helpers auto-route between inline base64 and uploaded file_id references based on size. Beta header gets added automatically when any block (including those nested in tool results) carries a file_id.
• ♻️ Reactive auto-compaction. Token estimator + LLM-driven ` / ` summarization, microcompact, session memory, post-cleanup file restoration. Long sessions stay inside the context window without losing critical state.
• 📦 Optional batteries. Companion agent-tools-code crate ships generic FileRead/Write/Edit, Grep/Glob (gitignore-aware via ignore), Bash, WebFetch, TodoWrite, NotebookEdit (Jupyter .ipynb cells), and ToolSearch for deferred-tool discovery. Every tool declares its SafetyClass; a WorkspacePolicy enforces path containment + size caps + symlink rules. Pull only the features you want.

---

Architecture

flowchart TB
    Host[Host application]
    subgraph Runtime[agent crate]
        QL[query - phase machine]
        Prov[provider - Anthropic / OpenAI / Ollama]
        Tool[tool trait + registry]
        Perm[permission - 7-step chain + matchers]
        Hook[hook - 27 typed events]
        Comp[compact - reactive auto-compact]
        Cost[cost - USD accounting]
        Sess[session - JSONL persistence]
        Atch[attachments - Files API]
        MCP[mcp - rmcp connector]
    end
    subgraph Optional[agent-tools-code]
        FS[FileRead / Write / Edit / ...]
        Search[Grep / Glob / ToolSearch]
        Shell[Bash]
        Web[WebFetch]
        Todo[TodoWrite]
    end
    Models[Models - Anthropic / OpenAI / Ollama / MCP]

    Host --> QL
    QL --> Prov
    QL --> Tool
    QL --> Hook
    QL --> Perm
    QL --> Comp
    QL --> Cost
    QL --> Sess
    Perm --> Tool
    Atch --> Tool
    Tool --> Optional
    Prov --> Models
    MCP --> Models

Streaming Events are the universal language: every provider emits the same Event taxonomy, so swap providers without touching tool code.

---

Install

Two crates, both versioned together. Pull only what you need.

[dependencies]
# Runtime — always
agent = { git = "https://github.com/ZSeven-W/agent-rs", default-features = false, features = ["anthropic", "session-jsonl"] }

# Optional: ready-made coding tool pack (FileRead/Write/Edit, Grep/Glob, Bash, WebFetch, TodoWrite, ToolSearch)
agent-tools-code = { git = "https://github.com/ZSeven-W/agent-rs", default-features = false, features = ["fs", "search"] }

agent features

| Flag | Pulls in | Notes | | --------------------------- | -------------------------------- | ---------------------------------------------------------- | | anthropic (default) | reqwest + eventsource-stream | Hand-rolled Anthropic SSE — no SDK dep. | | openai | async-openai 0.36 | OpenAI-compatible providers. | | ollama | ollama-rs 0.3 | Local models. | | mcp | rmcp 1.5 | MCP client + production stdio/HTTP connector + OAuth/PKCE. | | session-jsonl | fs4 | JSONL persistence with file lock. | | swarm | fs4 + notify | Sub-agents, mailbox, teams. | | tiktoken | tiktoken-rs | Real BPE token counts (cl100k / o200k / p50k / r50k). | | full | all of the above | |

agent-tools-code features

| Flag | Pulls in | Tools | | ------------------------ | --------------------- | ------------------------------------------------------------------------ | | fs (default) | (none) | FileRead / Write / Edit / ListDir / Mkdir / Move / Remove | | search (default) | regex + ignore | Grep · Glob (gitignore-aware) | | shell | shell-words | Bash (timeout, abort, output cap) | | bash-async | (none) | BashRun + BashOutput + KillShell (background shells, ring-buffer poll) | | web | reqwest + futures | WebFetch (HTML→text, size cap) | | web-search | web | WebSearch (pluggable backend, ships Tavily) | | task | futures | Task (spawn a child QueryLoop) | | todo | (none) | TodoWrite (in-memory shared state) | | notebook | (none) | NotebookEdit (Jupyter .ipynb cell-level edits) | | all | all of the above | |

ToolSearch is always-on (no feature flag) and lets you expose 50+ MCP tools without flooding the model's tool list — it picks them up via select:Name1,Name2 or keyword search.

---

Examples

Runnable examples live under each crate's examples/ directory:

| Example | Crate | What it shows | | ------------------- | ------------------ | ------------------------------------------------------------------------------------------------- | | anthropic_basic | agent | Minimal provider + QueryLoop + stream — the README TL;DR as a real binary. | | with_tools | agent | Wires the bundled coding tool pack into the loop and asks the model to grep + read the workspace. | | notebook_edit | agent-tools-code | Calls NotebookEditTool directly (no LLM) to edit a synthesized .ipynb. | | web_search_tavily | agent-tools-code | Tavily Search via WebSearchTool. Needs TAVILY_API_KEY. |

ANTHROPIC_API_KEY=sk-... cargo run --example anthropic_basic --features anthropic -p agent
ANTHROPIC_API_KEY=sk-... cargo run --example with_tools --features anthropic -p agent
cargo run --example notebook_edit --features notebook -p agent-tools-code
TAVILY_API_KEY=tv-... cargo run --example web_search_tavily --features web-search -p agent-tools-code

---

Quickstart with bundled tools

use agent::prelude::*;
use agent_tools_code::{register_default, WorkspacePolicy};
use std::sync::Arc;

let policy = WorkspacePolicy::new(std::env::current_dir()?)?.into_arc();
let mut tools = ToolRegistry::new();
register_default(&mut tools, policy);   // FileRead, Write, Edit, ListDir,
                                        // Mkdir, Move, Remove, Grep, Glob

let provider = Arc::new(AnthropicProvider::new(std::env::var("ANTHROPIC_API_KEY")?));
let qloop = QueryLoop::builder(provider, "claude-opus-4-7")
    .tools(Arc::new(tools))
    .build();

let mut stream = qloop.run("List the .rs files in src/, then summarize main.rs.", AbortController::new()).await?;
while let Some(event) = futures::StreamExt::next(&mut stream).await {
    match event? {
        Event::TextDelta { delta } => print!("{delta}"),
        Event::ToolUse { name, .. } => eprintln!("\n→ calling {name}"),
        _ => {}
    }
}

That's the full picture: registry → provider → loop. The runtime handles tool dispatch, permission gating, hooks, cost tracking, and auto-compaction without you wiring anything else.

---

Module surface

agent crate — runtime (15+ modules)

Foundation

| Module | Purpose | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | provider/ | Multi-provider LLM client. Tool definitions wired into request bodies; capability flags + streaming Event vocabulary. | | query/ | QueryLoop multi-turn phase machine. Reactive auto-compaction wired in. | | tool/ | Tool trait, ToolRegistry, SafetyClass lattice. Receipt-order concurrent execution via ToolExecutor. | | permission/ | 7-step chain + structured PermissionMatcher (Always / Field / ExactJson / AnyOf / AllOf / Not) + StringPattern. External-queue async approval. | | hook/ | 27 typed HookEvent variants. | | message/ | DAG-aware MessageStore. ContentBlock::Document for PDFs; ImageSource::File for Files-API references. | | stream/ | Event taxonomy: TextDelta / Thinking / ToolUse / ToolResult / Result / Usage / Error / Notice. | | session/ | JSONL persistence (schema v1) with atomic-rename + file lock. | | swarm/ | Sub-agents / teams. File-locked mailbox, in-process / tmux / iTerm2 backends. | | compact/ | Reactive auto-compaction. LLM-driven summarization, partial directions, microcompact, session memory. | | context/ | Sliding-window trim. |

Service layer

| Module | Purpose | | -------------- | ----------------------------------------------------------------------------------------------------- | | api/ | Retry with decorrelated jitter, error classification, prompt-cache-break detection, secret redaction. | | cost/ | Model-price-aware USD accounting. u128 nanodollars — no f64 drift. | | attachments/ | FilesClient + AnthropicFilesClient, smart size-aware routing. | | tokenizer/ | Pluggable trait. Real tiktoken plugs in via the trait. |

Discovery + extensibili

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ZSeven-W
• Source: ZSeven-W/agent-rs
• License: MIT
• Homepage: https://github.com/ZSeven-W/agent-rs

Install and usage instructions live in the source repository linked above.