everruns

Build durable, tool-using AI agents in Rust.

The Everruns Framework gives you the building blocks for agents that do real work: model providers, typed tools, multi-turn sessions, live events, cancellation, background work, files, workspaces, lifecycle hooks, MCP, and durable local state. It runs inside your Rust process, so you can start with one agent and grow into a custom runtime without replacing the core programming model.

Agent + Provider + Tools  ->  Engine  ->  Session  ->  Turns and Events

Quick start

Create a project and add Everruns with the OpenAI provider:

cargo add everruns --features openai
cargo add tokio --features macros,rt-multi-thread
export OPENAI_API_KEY=sk-...

Define a typed tool, give it to an agent powered by GPT-5.6 Terra, and run a turn:

use std::time::{SystemTime, UNIX_EPOCH};

use everruns::{Agent, Engine, OpenAI};

/// Return the current Unix time in seconds.
#[everruns::tool]
async fn current_time() -> Result<u64, String> {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|duration| duration.as_secs())
        .map_err(|error| error.to_string())
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let agent = Agent::builder()
        .name("assistant")
        .instructions("Use current_time when asked about time. Be concise.")
        .provider(OpenAI::from_env()?)
        .model("gpt-5.6-terra")
        .tool(current_time())
        .build()?;

    let session = Engine::new().create(agent);
    let turn = session.send_and_wait("What time is it?").await?;

    println!("{}", turn.response);
    Ok(())
}

#[everruns::tool] derives the tool's JSON schema and adapter from the Rust function. The model can call it during the turn, and the result is returned to the model before the final response is produced.

The programming model

Everruns keeps the core pieces explicit:

• Agent describes behavior: instructions, model, provider, tools, capabilities, files, and lifecycle hooks.
• Engine owns runtime resources and the session catalog. Keep it around when you want to resume sessions.
• Session is an isolated, multi-turn conversation. It exposes sending, steering, events, cancellation, history, and context inspection.
• Turn contains the response, status, iteration count, and tool-call count for one run.

Agents are immutable values. An engine snapshots an agent when it creates a session, which makes ownership and isolation predictable even when many sessions run concurrently.

Give agents tools and capabilities

For a single operation, annotate an async Rust function with #[everruns::tool] and add it with .tool(...). Inputs are deserialized into typed parameters, results are serialized for the model, and errors stay explicit.

Capabilities are the next step when a feature needs several tools, shared state, metadata, progress events, or call-scoped cancellation. Built-in and custom capabilities share one builder API:

use everruns::{Agent, CompactionConfig, ToolSearch};

let agent = Agent::builder()
    .instructions("Find the right tool and keep long sessions focused.")
    .provider(everruns::OpenAI::from_env()?)
    .model("gpt-5.6-terra")
    .capability(ToolSearch::automatic())
    .capability(CompactionConfig::new().budget_percent(0.85))
    .build()?;

You can also define reusable capability packages in Rust or load open, configuration-driven capability references. See Tools and macros, capability integrations, and authoring advanced capabilities.

Sessions that go beyond request/response

Use send_and_wait for a simple turn. Use send when you want to subscribe to events, steer a running agent, cancel work, or wait separately:

use everruns::{CancellationToken, RunOptions};

let mut events = session.events();
let pending = session.send("Research three options.").await?;

while let Some(event) = events.recv().await? {
    println!("{}", event.event_type());
    if event.kind.is_terminal() {
        break;
    }
}

let turn = pending.wait().await?;
println!("{}", turn.response);

let cancel = CancellationToken::new();
let options = RunOptions::new().cancel_token(cancel.clone());
cancel.cancel();
let stopped = session.run_with("Start another task.", options).await?;
assert!(!stopped.success);

The local feature adds a durable event log, session resume, scheduled work, and Git-backed workspace heads. Sessions can bind to isolated mutable project views and reopen the exact same workspace after a restart.

Features

The default feature set includes typed tools, capabilities, built-ins, and the session filesystem. Network providers and heavier runtime integrations are opt-in.

Combine features as needed:

cargo add everruns --features openai,bashkit,web-fetch,mcp

Examples

Every example imports only everruns. The example catalog includes the exact command for each one.

Start here

• hello — a small GPT-5.6 Terra agent with a typed tool and live events.
• production_agent — defensive tool boundaries and a multi-turn support agent.
• engine_sessions — engine ownership, isolated sessions, and resume.
• live_session — non-blocking sends, steering, and waiting.

Tools, capabilities, and orchestration

• capability_configuration — typed, code-defined, and dynamic capabilities through one API.
• advanced_capability — reusable tools, metadata, progress, typed results, and structured errors.
• subagents — concurrent child agents coordinated by a parent agent.
• github_monitor — background work that wakes an agent when a pull request check completes.
• session_work — session-owned tasks, delivery, and completion wakes.

Control, state, and observability

• observe_and_cancel — event streaming and cooperative cancellation.
• canonical_events — bounded canonical event recording and typed rendering.
• lifecycle_hooks — awaited agent, turn, tool, and completion handlers.
• session_history — durable resume and bounded history pages.
• workspace_policy — portable read/write scopes and trusted starter files.
• workspace_heads — isolated Git heads, environments, and durable workspace binding.

Documentation

• Framework guide
• Agents
• Models and providers
• Sessions
• Events and cancellation
• Persistence
• Workspaces and environments
• Custom providers
• Custom backends
• API reference

License

Licensed under the MIT License.