Waken

A lightweight runtime that routes work from a Source, to an interchangeable AI-agent Target, back through an Output.

Source → Runtime → Target → Response → Output

It is not an agent framework, an orchestration engine, a workflow builder, or an LLM wrapper — those are things you plug into it. Waken's own job is small on purpose: receive work, route it to the correct agent, return the result through the right channel. Think "nginx for AI agents," not "another LangGraph."

Install

pip install waken

Zero external services — no Docker, no Redis, no Postgres. State (sessions, scheduled jobs, retry queue) lives in one SQLite file, created automatically.

Target and channel adapters ship as separate packages (see ADR 0001) so core stays dependency-free, but they can be pulled in alongside waken with extras:

pip install waken[groq]          # a single adapter
pip install waken[groq,voice]    # several at once
pip install waken[all]           # every adapter

Available extras: claude, gemini, copilot, openai, mistral, cohere, groq, bedrock, ollama, voice, slack, telegram.

Quickstart

# app.py
from waken import Event, Response, Runtime, target_fn


@target_fn
async def echo(event: Event) -> Response:
    return Response(text=event.payload["prompt"])


runtime = Runtime()
runtime.target("echo", echo)
runtime.run()

waken run app.py

In another terminal:

waken send echo "Build tic tac toe." --wait
# Build tic tac toe.

That's it — runtime.run() is already reachable over HTTP (http://localhost:8080), with a CLI, a scheduler, and a retry queue on the same object, no extra setup. A real deployment swaps echo for a Target adapter (waken-claude, waken-gemini, ...) — same shape, same three lines.

What it does

• Sources turn something happening — an HTTP request, a webhook, a scheduled tick, a new file — into an Event.
• Targets receive an Event and return a Response. Swapping ClaudeAdapter() for GeminiAdapter() is a one-line change; nothing else in the runtime has to know.
• Outputs deliver a Response back through a channel (terminal, Slack, email, ...) — decoupled from wherever the Event came from.

runtime.target("claude", ClaudeAdapter())
runtime.target("gemini", GeminiAdapter())

@runtime.every(hours=1)
async def hourly_summary():
    await runtime.send(target="claude", prompt="Summarize today's commits.")

runtime.serve(port=8080)

More runnable examples: examples/ (scheduling, broadcasting to multiple targets, routing an inbound webhook).

CLI

waken run <script.py>          # execute a script that builds a Runtime and calls run()
waken send <target> <prompt>   # POST /send/<target> on a running instance
waken emit <event> <json>      # POST /emit/<event>
waken inspect                  # targets, sources, outputs, jobs, queue depth

Documentation

• Prior art review — what this fills that agent frameworks, MCP/A2A, and 2026's wave of "agent gateways" don't.
• Architecture Decision Record — the design and the alternatives it rejected.
• Public API specification — the full API, with examples.
• Implementation plan — milestones, and how the actual build diverged from the original plan along the way.

Status

Pre-release. The core API described above is implemented and tested. Target adapters (waken-claude, waken-gemini, waken-copilot, ...) and channel adapters (waken-voice, waken-slack, waken-telegram) ship as separate packages, published independently of core — see the ADR's alternatives for why core never depends on them.

Development

git clone https://github.com/WakenHQ/waken
cd waken
pip install -e ".[dev]"
pytest

License

MIT