AgentStateRouter (AEOE)

LLM routers optimize tokens. Real agent systems waste money on the wrong axis: the same task gets pinned to the most expensive model whether it needs it or not. AEOE optimizes for cost-per-unit-of-work on your own workload, scored against your own history, with the routing decision recorded as a commit you can blame later.

Why this matters

Three moments AEOE earns its keep

Pre-alpha — the foundation is in flight. Here's the shape of the engine.

Story 1 — The mixed batch

"Which model should run this task?"

A planning agent receives 50 tasks of mixed shape — some need code, some need long context, some are throwaway summaries. Without AEOE: a flat router pins everything to GPT-5 and burns budget.

With AEOE: call route(task) and get back the best model + parameters for this task type, scored on cost-per-unit-of-work and prior efficiency for the same shape. The decision is a commit. The outcome is a commit. The next batch sees both.

⚛ POST /route SCORED

task: code-review

context: 12,400 tokens

latency_budget: 5s

chosen: claude-sonnet-4.6

predicted_cost: $0.014

predicted_quality: 0.91

confidence: 0.87

reasoning: "prior 64 runs on code-review at this context size; sonnet beats opus on cost-per-unit-of-work by 4.2×"

Story 2 — The drop-in

"Don't rewrite the agent — change the base URL."

You already have a LiteLLM-shaped client. AEOE's proxy facade is OpenAI- and Anthropic-compatible — change the base URL, get optimized routing under the covers, keep every existing call site.

No rewrites. No new SDK. Same payloads, optimized routing, with the prior-run history visible in your AgentStateGraph store.

🔗 openai client (no rewrite) PROXY

from openai import OpenAI
client = OpenAI(
  base_url="https://router.aeoe.local/v1",
  api_key="sk-aeoe-...",
)
client.chat.completions.create(
  model="auto", # AEOE picks
messages=[...],
)

−47%

spend, last 1k

+0.04

quality delta

2.8×

efficiency

Story 3 — The learning loop

"Learn from your own history."

AEOE is built on AgentStateGraph. Every routing decision and its outcome is a commit. The next decision for a similar task sees the prior efficiency score — for your agents, on your task shapes, not a public leaderboard.

The engine improves on your workload. Yesterday's wins become tomorrow's defaults.

📊 history /tasks/code-review ASG

claude-opus-4.70.932h ago

claude-sonnet-4.60.914h ago

claude-sonnet-4.60.89yesterday

gpt-50.88yesterday

predicted best: claude-sonnet-4.6 · 87% conf

How it works

Every route decision answers nine questions

LiteLLM answers which key. AEOE answers everything else — and records the answer as a commit.

task_shape

What kind of work is this?

context_size

How much will it cost to send?

latency_budget

How fast does it need to come back?

cost_budget

How much are we willing to spend?

agent_id

Who is asking?

prior_efficiency

What worked last time?

policy

What's allowed?

chosen_model

Where does it go?

predicted_cost

What do we expect to pay?

Deploy It Anywhere

One engine, three shapes

Rust (core) HTTP / JSON-RPC (Suggester) OpenAI-compatible Anthropic-compatible Embedded crate MCP tools CLI Built on AgentStateGraph

Get Started

Run the Suggester in 60 seconds

terminal

What it is not

Clear on scope

AEOE is an optimization engine, not a key vault or a leaderboard.

NOT just an LLM router

LiteLLM/Helicone route on per-request rules. AEOE optimizes for workloads — cost-per-unit-of-work, efficiency score, agent history per task type.

NOT a leaderboard

Benchmarks score models on someone else's problems. AEOE scores them on yours, using your own commit history as ground truth.

License

Why BSL 1.1?

AgentStateRouter is built to become infrastructure for agent execution. Infrastructure primitives are strip-mining targets: cloud providers offer them as managed services, capture the value, and contribute nothing back. BSL 1.1 closes that gap.

✓ Individuals, startups, and enterprises using AEOE internally — including in production — are unaffected.

⚠ The restriction covers one specific case: offering AEOE as a hosted routing service to third parties without a commercial agreement.

↺ After four years, each version converts to Apache 2.0 permanently, with no conditions.

Part of a family

Built on AgentStateGraph

AEOE is the optimization engine. AgentStateGraph is the substrate that makes prior-run scoring history possible. OpenClaw is the reference embedded consumer.

Visit agentstategraph.dev GitLab