Awaken

English | 中文

Build agent capability in Rust. Tune prompts, models, permissions, skills, and eval loops live. Serve AI SDK, AG-UI, A2A, MCP, and ACP clients from one runtime without turning each agent into a fragile script.

Docs: Awaken docs · 中文文档 · Changelog. MSRV: Rust 1.93. The published crate is awaken; awaken-agent is a compatibility republish from when the project shipped under that name.

30-second version

Start the local server and Admin Console:

AWAKEN_HTTP_ADDR=127.0.0.1:38080 \
AWAKEN_ADMIN_API_BEARER_TOKEN=dev-token \
AWAKEN_STORAGE_DIR=./target/awaken-dev \
cargo run -p ai-sdk-starter-agent

pnpm --filter awaken-admin-console dev

Open http://127.0.0.1:3002, paste dev-token, configure a provider-backed model, then create or tune an agent. Without an API key, the starter backend uses a deterministic scripted executor so you can verify the server routes and console first.

The tune-first loop is:

Validate draft -> Preview chat -> Save snapshot -> Run task -> Inspect trace -> Capture dataset/eval -> Adjust

Why Awaken

• Code stays stable. Tools, typed state, providers, stores, and plugins live in Rust.
• Behavior tunes live. Prompts, model bindings, tool descriptions, permission rules, reminders, skills, delegates, and plugin sections change through managed config.
• One backend serves many clients. AI SDK v6, AG-UI / CopilotKit, A2A, MCP, and ACP are adapters over the same runtime event stream and run model.
• Runs are operational objects. Durable dispatch, HITL mailbox suspension, cancellation, trace capture, replay, datasets, eval runs, and audit restore are runtime/server contracts.
• State and tools are typed. StateKey, generated JSON Schema for TypedTool, pure tool gating, and atomic commits make concurrent tool work auditable.

Tune-first workflow

Awaken treats agent behavior as managed resources, not scattered code edits. Server config writes are validated, published as registry snapshots, and auditable when stores are wired.

Tools are written once and stay stable. Models, agents, prompts, skills, delegates, and policy sections are tuned through /v1/config/* or the Admin Console — Validate → Save → preview-chat → adjust.

Choose your mode

Awaken separates the agent execution loop from the service control plane.

Runtime mode is in-process library use inside a standard async Rust program. It is not a no_std or Tokio-free embedded target. Server mode wraps the same runtime with protocols, durable dispatch, managed config, audit/restore, trace/eval storage, and the browser workflow.

Quickstart A: server + Admin Console

Use this path when you want the tuning workflow first.

AWAKEN_HTTP_ADDR=127.0.0.1:38080 \
AWAKEN_ADMIN_API_BEARER_TOKEN=dev-token \
AWAKEN_STORAGE_DIR=./target/awaken-dev \
cargo run -p ai-sdk-starter-agent

pnpm install
pnpm --filter awaken-admin-console dev

Open http://127.0.0.1:3002, click the token pill, and paste dev-token. Configure a provider/model, create an agent, preview it, then copy the AI SDK or AG-UI route from the saved agent page.

Useful docs:

• Get Started
• Use the Admin Console
• Configure Agent Behavior
• Capture a Dataset and Run an Eval

Quickstart B: runtime library

Use this path when your Rust application owns the I/O boundary and calls the runtime directly.

Prerequisites: Rust 1.93+ and an OpenAI-compatible API key.

[dependencies]
awaken = { git = "https://github.com/AwakenWorks/awaken" }
tokio = { version = "1", features = ["full"] }
async-trait = "0.1"
serde_json = "1"

These snippets follow the current main-branch API. Use the 0.5 to 0.6 migration guide when upgrading from the published 0.5 line.

export OPENAI_API_KEY=<your-key>

src/main.rs:

use awaken::engine::GenaiExecutor;
use awaken::prelude::*;
use async_trait::async_trait;
use serde_json::json;
use std::sync::Arc;

struct EchoTool;

#[async_trait]
impl Tool for EchoTool {
    fn descriptor(&self) -> ToolDescriptor {
        ToolDescriptor::new("echo", "Echo", "Echo input back to the caller").with_parameters(json!({
            "type": "object",
            "properties": { "text": { "type": "string" } },
            "required": ["text"]
        }))
    }

    async fn execute(&self, args: JsonValue, _ctx: &ToolCallContext) -> Result<ToolOutput, ToolError> {
        let text = args["text"].as_str().unwrap_or_default();
        Ok(ToolResult::success("echo", json!({ "echoed": text })).into())
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = AgentRuntimeBuilder::new()
        .with_agent_spec(
            AgentSpec::new("assistant")
                .with_model_id("gpt-4o-mini")
                .with_system_prompt("You are helpful. Use the echo tool when asked.")
                .with_max_rounds(5),
        )
        .with_tool("echo", Arc::new(EchoTool))
        .with_provider("openai", Arc::new(GenaiExecutor::new()))
        .with_model(ModelSpec::new("gpt-4o-mini", "openai", "gpt-4o-mini"))
        .build()?;

    let request = RunActivation::new("thread-1", vec![Message::user("Say hello using the echo tool")])
        .with_agent_id("assistant");

    let result = runtime.run_to_completion(request).await?;
    println!("{}", result.response);
    Ok(())
}

Use runtime.run(request, sink) instead of run_to_completion when you need to stream events to SSE, WebSocket, protocol adapters, or tests. For a longer example, see crates/awaken/examples/multi_turn.rs.

The quickstart path is covered without network access:

cargo test -p awaken --test readme_quickstart        # offline scripted provider
OPENAI_API_KEY=<key> cargo test -p awaken --test readme_live_provider -- --ignored  # live provider

Protocols

Frontend guides: AI SDK · CopilotKit / AG-UI · HTTP SSE.

Extensions

The facade full feature pulls in the plugins below. Use default-features = false to opt out. awaken-ext-deferred-tools is a companion crate and is added as a direct dependency.

Write your own with ToolGateHook or BeforeToolExecute — same trait signatures the built-ins use.

Architecture

awaken                   Facade crate with feature flags
├─ awaken-runtime-contract Runtime contracts: specs, tools, events, state, commit coordinator
├─ awaken-server-contract  Server/store contracts: queries, scoped stores, mailbox/outbox, staged commits
├─ awaken-runtime        Resolver, phase engine, loop runner, runtime control
├─ awaken-server         HTTP routes, SSE replay, mailbox dispatch, protocol adapters
├─ awaken-stores         Thread + run + config + mailbox + profile stores
├─ awaken-tool-pattern   Glob/regex matching used by extensions
└─ awaken-ext-*          Optional extensions and companion plugins

For details, start with Architecture and Run Lifecycle and Phases.

When this fits

• You want a Rust backend for AI agents with compile-time guarantees.
• You need to serve AI SDK, CopilotKit, A2A, MCP, and/or ACP from a single backend.
• Tools need to share state safely during concurrent execution, and runs need auditable history with checkpoints and resume.
• Operators need to tune prompts, models, permissions, skills, traces, datasets, and evals without changing code.

When it does not

• You need built-in file/shell/web tools out of the box — consider OpenAI Agents SDK, Dify, or CrewAI.
• You want a visual workflow builder — consider Dify or LangGraph Studio.
• You want Python and rapid prototyping — consider LangGraph, AG2, or PydanticAI.
• You need an LLM-managed memory subsystem where the agent decides what to remember — consider Letta.

Examples and learning paths

Examples:

Contributing

Setup in CONTRIBUTING.md and DEVELOPMENT.md. Good first issues is the entry-point label. Conversation: GitHub Discussions.

Acknowledgement

The awaken crate name on crates.io was transferred from @brayniac, who maintained an earlier crate under the same name. Versions 0.1–0.3 of awaken on crates.io belong to that earlier project; this codebase resumes the line that previously shipped as awaken-agent 0.2.x and starts at 0.4.0 to skip past those versions. Thank you.

License

Dual-licensed under MIT or Apache-2.0.