Awaken

runtime library · server control plane

Production AI agent backend for Rust.

Build agent capabilities once in Rust, tune and operate them live, and serve every client from the same runtime. Use direct runtime for in-process app flows or server mode for protocols, durable runs, and the admin console.

Get started Star on GitHub

Rust 1.93 MSRV unsafe_code = "forbid" Install:

src/main.rs main branch API

use awaken::contract::message::Message;
use awaken::engine::GenaiExecutor;
use awaken::registry_spec::{AgentSpec, ModelSpec};
use awaken::{AgentRuntimeBuilder, RunActivation};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let spec = AgentSpec::new("assistant")
        .with_model_id("gpt-4o-mini")
        .with_system_prompt("You are helpful.");

    let rt = AgentRuntimeBuilder::new()
        .with_agent_spec(spec)
        .with_provider("openai", Arc::new(GenaiExecutor::new()))
        .with_model(ModelSpec::new("gpt-4o-mini", "openai", "gpt-4o-mini"))
        .build()?;

    let req =
        RunActivation::new("thread-1", vec![Message::user("Hello!")]).with_agent_id("assistant");

    let out = rt.run_to_completion(req).await?;
    println!("{}", out.response);
    Ok(())
}

Mental model

Runtime for code, server for operations

Runtime mode keeps executable capability in Rust: tools, providers, state, plugins, and direct RunActivation execution. Server mode wraps it with durable runs, protocols, and managed config.

Tune & Operate →

Code (Rust)

Tools · State · Plugins

Tools as Tool / TypedTool impls with `schemars`-derived JSON Schema. State is typed: `StateKey` declares merge strategy + scope; commits are atomic per phase. Plugins hook the 9-phase loop by name.

Config (declarative)

Providers · Models · Agents · Skills

Mutate through /v1/config/* (REST) or the admin console (UI) — both are server surfaces over the same registry snapshot. Existing runs keep their resolved spec; new runs pick up the edit.

Server surface

Five protocols without five agents

The server translates each wire format into the same runtime event stream and run model. Switch clients without touching agent code.

Wire-format reference →

SDK

AI SDK v6

POST /v1/ai-sdk/chat

Stream chunks to Vercel AI SDK's useChat() — text, tool calls, and finish events.

React · Next.js

AG-UI

POST /v1/ag-ui/run

CopilotKit's <CopilotKit> drop-in for chat, generative UI, and HITL.

CopilotKit

A2A

POST /v1/a2a/message:send

Agent-to-agent messaging — let other agents call yours as a remote sub-agent.

Foreign agents

MCP

POST /v1/mcp

JSON-RPC 2.0 surface for MCP-compatible clients over the server route.

Claude · Cursor · Zed

ACP

stdio serve_stdio

Agent Client Protocol stdio adapter from the server crate.

ACP hosts

Admin Console

Operate it like a product, not a script

A React 19 SPA wired to the server APIs. Manage agents, models, providers, skills, MCP, traces, datasets, and eval runs from the same control plane.

Open console guide →

localhost:3002/agents

Agents

registered

Tools

built-in + plugin + MCP

AgentModelInferences (24h)

assistant gpt-4o-mini 2.1k

researcher claude-3.7 847

summariser deepseek-v3 112

Config = control plane

Spec-first, snapshot-applied

Models, providers, prompts, permissions, MCP — edit the spec and the server publishes a registry snapshot for later runs.

Docs stay executable

Workspace tests and doctests guard the examples

The workspace runs with unsafe_code = "forbid". Public examples are covered by compile tests, doctests, and docs build checks.

Inside the runtime

A 9-phase loop, not a DAG

Every run flows through nine typed phases. Plugins hook in by name. State commits atomically at the end of each round.

Phase reference →

1 resolve

2 prepare

3 prompt

4 stream

5 gate

6 tool

7 commit

8 events

9 finalize

Snapshot in, batch out.

Each phase reads an immutable state snapshot and returns a typed mutation batch. commit applies the batch atomically — no partial writes, no surprise interleaving when tools run in parallel. The pure gate phase decides which tool calls to authorise before tool executes; permission, reminder, and HITL plugins all hook here.

Stream recovery built in. Idle stalls and mid-stream errors are caught with four explicit plans: continue text, replay completed tools, restart with a cancelled-tool hint, or whole restart. Retry-After is honoured; checkpoints persist across process restarts.

Plugins

Batteries that opt in

Seven typed extension surfaces, each gated by a cargo feature flag. Same trait Plugin + hooks the built-ins use — write your own with no special API.

Plugin reference →

Permission

permission

Allow / Deny / Ask rules on tool name + args. Ask suspends the run for HITL via the mailbox.

Reminder

reminder

Inject system or conversation-level messages when a tool call matches a pattern.

Observability

observability

OpenTelemetry traces + metrics in GenAI semantic conventions. OTLP / file / in-memory.

MCP

mcp

Connect to any MCP server — its tools register as native Awaken tools.

Skills

skills

Skill packages discovered and injected as a catalog — the LLM activates on demand.

Generative UI

generative-ui

Stream declarative UI via A2UI, JSON Render, and OpenUI Lang.

Deferred Tools

deferred-tools

Hide large tool schemas behind a ToolSearch step; idle tools re-defer via a Beta usage model.

Write your own

trait Plugin

Same hooks: ToolGateHook, BeforeToolExecute, PluginConfigKey.