Awaken

Quickstart: runtime mode

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 (run with cargo run):

,no_run
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 end-to-end example (multi-turn + persistent threads), 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

Examples and learning paths

```bash export OPENAI_API_KEY=<your-key> cargo run --package awaken --example multi_turn

pnpm install && pnpm --filter awaken-ai-sdk-starter dev

Optional: seed sample agents/tools for demos

AWAKEN_SEED_PROFILE=demo AWAKEN_STORAGE_DIR=./target/admin-sessions cargo run -p ai-sdk-starter-agent

Built-in plugins

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

Write your own with ToolGateHook (pure gate decisions) or BeforeToolExecute (execution-time hooks) — same trait signatures the built-ins use.