Skip to content

RigelNana/Agenium

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

4 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

🜛 Agenium

The elemental building block for AI agents. Written in Rust.

Rust License CI Crates.io docs.rs codecov Discord Stars


The periodic table had 118 elements. Now it has 119.
Type-safe. Blazing fast. Zero-copy streaming. No garbage collection pauses.
One framework. One language. One binary. Infinite agents.


Get Started · Architecture · Examples · Docs


Why Agenium?

Every major AI coding agent — Claude Code, Cursor, OpenCode, Windsurf — runs the same core loop: Input → Think → Output → repeat. They're all written in TypeScript. We asked: what if this loop was written in Rust?

Agenium TypeScript agents
Startup time ~5ms ~500ms
Memory (idle) ~8 MB ~120 MB
Streaming latency Zero-copy SSE JSON.parse per chunk
Type safety Compile-time (enums, traits) Runtime (zod, ajv)
Concurrency Tokio async + true parallelism Single-threaded event loop
Deployment Single static binary node_modules + runtime
Tool execution Sandboxed, parallel Sequential, trust-based

✨ Features

  • 🔄 ITO Agent Loop — Input → Think → Output cycle with automatic tool calling, retry, and context compression
  • 🧠 Multi-Provider — OpenAI, Anthropic, DeepSeek (V4 thinking mode), and any OpenAI-compatible API
  • 🛠️ Rich Tool System — 10 built-in tools (Read, Edit, Write, Bash, Grep, Glob, Todo, AskUser, WebFetch, MCP) with JSON Schema validation
  • 🔐 Permission Gates — Configurable approval policies per tool (AllowAll, DenyAll, Interactive, or custom)
  • 📦 Context Engine — Automatic compression when approaching token limits, with cache-aware prompt building
  • 🧩 MCP Support — Connect to any Model Context Protocol server for unlimited tool extension
  • 💾 Session Persistence — Save/resume conversations with JSONL storage backend
  • 🎯 Prompt Builder — Multi-block system prompts with per-block cache hints (Anthropic ephemeral caching)
  • 🔭 Observability — OpenTelemetry traces, structured logging, token usage tracking
  • 🏖️ Sandbox Execution — Commands run in isolated sandbox with configurable timeout and working directory
  • ⚡ Streaming Events — Real-time AgentEvent stream for building rich UIs (TUI, Web, Desktop)

Crate Map

Crate Purpose
agent-core Agent loop, conversation, events, message system
agent-provider LLM adapters (OpenAI, Anthropic) + streaming SSE parser
agent-tool Tool trait, schema validation, execution engine
agent-tools 10 built-in tools + ToolSet builder with profiles
agent-context Token counting, context compression
agent-permission Permission gates, approval hooks
agent-prompt Prompt registry, builder, cache-hinted blocks
agent-session Session persistence (JSONL), resume, auto-titling
agent-sandbox Sandboxed command execution
agent-mcp Model Context Protocol client
agent-vault API key resolution + secret management
agent-observe OpenTelemetry integration
agent-skill Skill/plugin system

🚀 Quick Start

git clone https://github.com/RigelNana/agenium.git
cd agenium/examples/agent-cli
cp .env.example .env
# Edit .env with your API key (OpenAI, Anthropic, or DeepSeek)
cargo run -p agent-cli
╔══════════════════════════════════════════════════╗
║            Agenium CLI v0.1.0                    ║
╠══════════════════════════════════════════════════╣
║  Provider : openai                               ║
║  Model    : deepseek-v4-flash                    ║
║  Base URL : https://api.deepseek.com/v1          ║
╠══════════════════════════════════════════════════╣
║  /clear — reset  /cost — usage  /quit — exit     ║
╚══════════════════════════════════════════════════╝

  Tools: 7 registered

❯ Check if Python is installed and show pip list
⚙ Bash ✓
⚙ Bash ✓
Python 3.12.0 is installed. Here are your packages:
  pip          24.0
  setuptools   69.5.1
  ...

(12536 in / 392 out, 12160 cache-read)

📝 Usage

Minimal Agent (10 lines)

use agent_core::agent::{Agent, AgentConfig};
use agent_provider::OpenAIProvider;

let provider = OpenAIProvider::new("https://api.openai.com/v1", &api_key);
let agent = Agent::new(AgentConfig {
    provider: Box::new(provider),
    model: Model::openai("gpt-4o"),
    system_prompt: "You are a helpful assistant.".into(),
    tools: vec![],  // add tools here
    ..Default::default()
});

let result = agent.query("Hello!", &cancel, |event| {
    // handle streaming events
}).await?;

With Tools

use agent_tools::tool_set::ToolSet;
use agent_sandbox::local::LocalSandbox;

let sandbox = Arc::new(LocalSandbox::new("/tmp/workspace"));
let tool_set = ToolSet::cli(sandbox)
    .with_web_fetch(Arc::new(DefaultFetcher))
    .build();

let agent = Agent::new(AgentConfig {
    tools: tool_set.tool_definitions(),
    ..config
});

Web Server (Axum + SSE)

async fn chat(State(agent): State<Agent>) -> Sse<impl Stream<Item = Event>> {
    let (tx, rx) = mpsc::channel(32);

    tokio::spawn(async move {
        agent.query(&input, &cancel, move |event| {
            if let AgentEvent::MessageUpdate { event: AssistantMessageEvent::TextDelta { delta, .. }, .. } = event {
                tx.blocking_send(Event::default().data(delta)).ok();
            }
        }).await;
    });

    Sse::new(ReceiverStream::new(rx))
}

Session Persistence

use agent_session::{SessionManager, SessionBoundAgent};

let manager = SessionManager::new(FileSystemStorage::new("./sessions"));
let mut bound = SessionBoundAgent::create(manager, agent_config, session_config).await?;

// Conversations auto-persist across prompts
bound.prompt("Fix the login bug", &cancel).await?;

// Resume later
let mut bound = SessionBoundAgent::resume(manager, session_id, agent_config).await?;
bound.prompt("What was I working on?", &cancel).await?;

🧪 Examples

Example Description
agent-cli Full interactive CLI agent with all tools
agent-demo Minimal demos for each feature
live-test Live integration tests against real APIs

🔧 Supported Providers

Provider Status Thinking Mode Tool Calls Streaming
OpenAI (GPT-4o, o3, etc.)
Anthropic (Claude 4, Sonnet)
DeepSeek (V4 Flash/Pro) reasoning_content passback
OpenAI-compatible (Ollama, vLLM, etc.)

🛠️ Built-in Tools

Tool Description
Read Read files with line numbers, image support
Edit Find-and-replace edits, new file creation
Write Write entire file contents
Bash Sandboxed shell commands with timeout
Grep Ripgrep-powered parallel search
Glob File pattern matching
TodoWrite Structured task tracking
AskUser Interactive user questions with options
WebFetch URL content fetching with summarization
MCP Connect any MCP server as tools

🤝 Contributing

Contributions welcome! Please read our Contributing Guide before submitting a PR.

# Run all tests
cargo test --workspace

# Run with logging
RUST_LOG=agent_core=debug,agent_provider=debug cargo run -p agent-cli

📄 License

Dual-licensed under MIT or Apache-2.0 at your option.


Ag — Element 119. Synthesized in Rust. Stable at mass scale.

⭐ Star this repo · 🐛 Report Bug · 💡 Request Feature

About

The elemental Rust framework for building production-grade AI agents.

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages