# Everruns Framework

**Navigation:** [Products](/products/) | [Platform](/products/platform/) | [Blog](/blog/) | [Docs](https://docs.everruns.com/framework/) | [GitHub](https://github.com/everruns/everruns)

---

> 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.

```bash
cargo add everruns
```

- **1**: crate to add
- **0**: services to run
- **15**: runnable examples
- **MIT**: license

```rust
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(())
}
```

---

## 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 + Tools -> Engine -> Session -> Turns 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.

---

## 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.

```rust
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.");
```

---

## 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.

| Feature | Adds |
| --- | --- |
| `openai` | OpenAI Responses API provider configuration |
| `bashkit` | Sandboxed shell execution |
| `web-fetch` | HTTP content fetching |
| `duckduckgo` | DuckDuckGo search |
| `lua` | Lua execution |
| `mcp` | Remote HTTP MCP servers |
| `mcp-stdio` | Local-process MCP servers, plus HTTP MCP |
| `local` | Durable local sessions, work, schedules, and Git workspace heads |
| `a2a` | Outbound Agent2Agent delegation; includes `local` |

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

---

## 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](/products/platform/) and [Everruns Cloud](/cloud/).

> The 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

---

## One dependency, one turn.

1. **Add the crate.** One dependency plus a Tokio runtime. Add `--features openai` when you want a real model rather than the simulator.
2. **Describe the agent.** Instructions, a model, and the typed tools it may call. `Agent::builder()` returns an immutable value you can clone across sessions.
3. **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.
4. **Keep going.** Turn on `local` for durable sessions, resume, scheduled work, and Git-backed workspaces, still with no services to operate.

```bash
$ cargo new oncall && cd oncall
$ cargo add everruns --features openai
$ cargo add tokio --features macros,rt-multi-thread
$ export OPENAI_API_KEY=sk-...
$ cargo run
# turn.started
# tool.completed
# turn.completed
checkout is healthy
```

---

## Complete programs, maintained with the crate.

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

- [`hello`](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/hello.rs): A small agent with a typed tool and live events.
- [`production_agent`](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/production_agent.rs): Defensive tool boundaries and a multi-turn support agent.
- [`engine_sessions`](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/engine_sessions.rs): Engine ownership, isolated sessions, and resume.
- [`advanced_capability`](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/advanced_capability.rs): Reusable tools, metadata, progress, typed results, and structured errors.
- [`subagents`](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/subagents.rs): Concurrent child agents coordinated by a parent agent.
- [`github_monitor`](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/github_monitor.rs): Background work that wakes an agent when a pull request check completes.
- [`observe_and_cancel`](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/observe_and_cancel.rs): Event streaming and cooperative cancellation.
- [`workspace_heads`](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/workspace_heads.rs): Isolated Git heads, environments, and durable binding.

[All 15 examples](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/README.md)

---

## 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.

Install: `cargo add everruns`

Crate: https://crates.io/crates/everruns

Docs: https://docs.everruns.com/framework/

GitHub: https://github.com/everruns/everruns

---

## Machine-readable entry points

- [/llms.txt](https://everruns.com/llms.txt): index of this site written for language models.
- [/llms-full.txt](https://everruns.com/llms-full.txt): every page on this site as one document.
- [/auth.md](https://everruns.com/auth.md): how an agent obtains Everruns API credentials.
- [/.well-known/ai-catalog.json](https://everruns.com/.well-known/ai-catalog.json): ARD capability manifest.
- [/.well-known/mcp/server-card.json](https://everruns.com/.well-known/mcp/server-card.json): MCP server card for Everruns Cloud.
- [/.well-known/agent-skills/index.json](https://everruns.com/.well-known/agent-skills/index.json): agent skills for working with Everruns.

Any page on this site serves Markdown to `Accept: text/markdown`.