# Agent Rs > Pure-Rust async runtime for LLM agents. Multi-provider (Anthropic/OpenAI/Ollama), tool-capable end-to-end, structured permissions, real MCP support, USD cost tracking, Files API, optional FS+search tool pack. - **Type:** MCP server - **Install:** `agentstack add mcp-zseven-w-agent-rs` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [ZSeven-W](https://agentstack.voostack.com/s/zseven-w) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [ZSeven-W](https://github.com/ZSeven-W) - **Source:** https://github.com/ZSeven-W/agent-rs - **Website:** https://github.com/ZSeven-W/agent-rs ## Install ```sh agentstack add mcp-zseven-w-agent-rs ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # `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) ```text ┌─ user ──┐ ┌─── QueryLoop ───────────────────────────────────────┐ │ prompt │───▶│ Streaming → ToolDispatch → ToolCollecting → Yield │──▶ Event::* └─────────┘ │ ↑ │ │ │ └──── auto-compact / hooks / cost ◀─────┘ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ▼ ▼ ▼ ▼ Anthropic OpenAI-* Ollama MCP servers (SSE) (compat) (local) (stdio / HTTP) ``` --- ## TL;DR ```rust 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](https://github.com/ZSeven-W/zode) - an AI-native coding CLI for terminal workflows, built around a Rust microkernel, plugins, multi-provider models, and a full-screen TUI. - [jian](https://github.com/ZSeven-W/jian) - a Rust-native cross-platform UI framework where an `.op` file can be an app. - [noema](https://github.com/ZSeven-W/noema) - local-first, non-vector memory for coding agents, including review queues, lexical recall, MCP, S3 offload, and enterprise policy controls. - [OpenPencil](https://github.com/ZSeven-W/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 ```mermaid 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. ```toml [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`. | ```sh 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 ```rust 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](https://github.com/ZSeven-W) - **Source:** [ZSeven-W/agent-rs](https://github.com/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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-zseven-w-agent-rs - Seller: https://agentstack.voostack.com/s/zseven-w - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.