The everruns crate · Rust · MIT

Build capable AI agents inside your own process.

The Everruns Framework is the application-facing everruns crate. It lets Rust applications describe and run agents without first becoming execution-host implementers: instructions, models, tools, sessions, observation, and controlled extension.

Framework guide →

crate to add

services to run

runnable examples

MIT

license

main.rs

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

/// Report whether a service is healthy.
#[everruns::tool]
async fn service_health(name: String) -> Result<String, String> {
    Ok(format!("{name}: healthy"))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let agent = Agent::builder()
        .name("oncall")
        .instructions("Answer on-call questions. Be terse.")
        .provider(OpenAI::from_env()?)
        .model("gpt-5.6-terra")
        .tool(service_health())
        .build()?;

    let session = Engine::new().create(agent);
    let mut events = session.events();
    let pending = session.send("is checkout healthy?").await?;

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

    println!("{}", pending.wait().await?.response);
    Ok(())
}

The programming model

Four pieces, all explicit.

No graph to compile, no orchestration DSL to learn. An agent is a value, an engine runs it, and a session is a conversation you can observe, steer, and cancel.

Agent + Provider + ToolsEngineSessionTurns and Events

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

An isolated, multi-turn conversation. It exposes sending, steering, events, cancellation, history, and context inspection.

Turn

One run: the response, its status, the iteration count, and the number of tool calls it took.

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

Default build

It runs offline before it runs anything else.

The default feature set is typed tools, capabilities, built-ins, and the session filesystem. A simulated model runs a full turn with no database, server, worker, network connection, or provider credential, which is also how you test agents in CI.

Typed tools from Rust signatures. #[everruns::tool] derives the JSON schema and the adapter from an async function. Inputs deserialize into typed parameters, results serialize back for the model, and errors stay explicit.

Capabilities when one tool is not enough. Package several tools with shared state, metadata, progress events, and call-scoped cancellation, or configure built-ins like tool search and compaction through the same builder.

An open provider boundary. Simulate a model, use OpenAI, or attach your own ChatDriver. There is no closed provider enum in your application code.

Events, steering, and cancellation. Subscribe to a running turn, steer it mid-flight, or stop it cooperatively with a CancellationToken instead of dropping a future.

Lifecycle hooks at execution boundaries. Awaited handlers at agent, turn, tool, and completion boundaries, so audit logging and policy live in your code, not in a fork.

Persistence you choose. Start with Engine-lifetime memory, add crash-durable local state and Git-backed workspaces with one feature, or cross deliberately into a custom backend.

tests/agent.rsno credential needed

let agent = Agent::builder()
    .instructions("Answer in one short sentence.")
    .model(Model::simulated("Hello from Everruns."))
    .build()?;

let turn = Engine::new()
    .create(agent)
    .send_and_wait("Say hello.")
    .await?;

assert_eq!(turn.response, "Hello from Everruns.");

Cargo features

Every edge to the outside world is opt-in.

Network providers and heavier runtime integrations are features you turn on, one at a time. What you do not enable is not compiled into your binary, and not advertised to the model.

openaiOpenAI Responses API provider configuration

bashkitSandboxed shell execution

web-fetchHTTP content fetching

duckduckgoDuckDuckGo search

luaLua execution

mcpRemote HTTP MCP servers

mcp-stdioLocal-process MCP servers, plus HTTP MCP

localDurable local sessions, work, schedules, and Git workspace heads

a2aOutbound Agent2Agent delegation; includes local

Combine them as needed: cargo add everruns --features openai,bashkit,web-fetch,mcp

Framework, Runtime, SDKs, Platform

Which surface you are actually on.

These four names mean four different things in Everruns, and picking the wrong one costs you weeks. The Framework is where a normal Rust application starts.

Framework

The everruns crate.

Rust applications, libraries, CLIs, desktop apps, services, and tests that build and run agents in process. This page.

Runtime

Low-level host execution.

The everruns-host crate and its focused siblings, for advanced hosts that replace storage or orchestration. Not a product name, and not a synonym for the Framework.

SDKs

Remote clients.

Typed Rust, Python, and TypeScript clients that call a running Everruns server. They do not embed Framework execution in the client process.

Platform

Agents as a service.

The control plane, server, workers, UI, durable storage, and deployment topology. See Everruns Platform and Everruns Cloud.

// straight from the source repoThe Everruns Framework lets Rust application authors describe and run agents without first becoming execution-host implementers. A normal application begins there and should not need to construct stored domain records, backend registries, worker phases, or a control plane to run an agent. - Framework Purpose and Terminology, everruns/everruns

Quickstart

One dependency, one turn.

Add the crate.

One dependency plus a Tokio runtime. Add --features openai when you want a real model rather than the simulator.

Describe the agent.

Instructions, a model, and the typed tools it may call. Agent::builder() returns an immutable value you can clone across sessions.

Run a turn.

Create a session from an Engine and call send_and_wait, or use send when you want to observe events, steer, or cancel.

Keep going.

Turn on local for durable sessions, resume, scheduled work, and Git-backed workspaces, still with no services to operate.

Runnable examples

Complete programs, maintained with the crate.

Every example imports only everruns, and each one ships with the exact command to run it.

helloA small agent with a typed tool and live events.production_agentDefensive tool boundaries and a multi-turn support agent.engine_sessionsEngine ownership, isolated sessions, and resume.advanced_capabilityReusable tools, metadata, progress, typed results, and structured errors.subagentsConcurrent child agents coordinated by a parent agent.github_monitorBackground work that wakes an agent when a pull request check completes.observe_and_cancelEvent streaming and cooperative cancellation.workspace_headsIsolated Git heads, environments, and durable binding.

All 15 examples →

Start with one crate.

The Framework runs in your process today. When you need multi-tenant deployment, a control plane, an operator console, and delivery channels, the same agents move to the platform without changing how they are defined.

Framework quickstart crates.io/crates/everruns ↗

Documentation GitHub All products