agentcents 1.0.0

LLM API cost interceptor and budget enforcer for AI agents

agentcents

Stop overpaying for the wrong model.

agentcents sits between your agent and any LLM. Before each call it forecasts the cost as an honest range — measured input, estimated output, per candidate model — tracks every cent you actually spend, and proves its own forecasting accuracy on a calibration page. Point your client at it. Change nothing else.

pip install agentcents

No API keys. No accounts. No code changes beyond one base URL.

---

New in 0.2.5

The release where agentcents stops just watching and starts forecasting:

• agentcents explain — EXPLAIN COST for an LLM call. Pipe a request in, get every candidate model priced as a p50 → p90 range before you spend. Input tokens are measured; output tokens are estimated from your own workload's histogram — and when two candidates swap rank inside the range, the decision is flagged unstable instead of pretending to certainty.
• Calibration page (/explain) — every proxied call silently logs its forecast next to what it actually cost. Coverage gauges, q-error, and a per-call calibration strip show whether the estimator has earned your trust. agentcents explain --accuracy gives the same report in the terminal.
• Orchestrator page (/orchestrator) — the plan-chooser, shown before it binds: per-node routing decisions, each gated by robustness, a capability quality floor, tool-use and provider-boundary rules. Advisory today; auto-apply only unlocks once the calibration page shows the forecasts hold.
• Two Cents — a neutral cost guide built into every dashboard page. It answers from your own ledger, runs on your own local model by default (~$0 per answer, metered in your own dashboard), and is allowed to say "use the free local model" — because it isn't selling tokens.
• Cache-aware cost accounting — cached input tokens (OpenAI prompt_tokens_details, Anthropic cache_read/creation_input_tokens) are now priced correctly. Previously, heavily-cached traffic was over-counted by the cache discount; ledgers are accurate from this release forward.
• Redesigned dashboard — a ledger, not a cockpit — with dark mode.

---

The problem

Most agents pick one frontier model and use it for everything — classifying, retrieving, the hard reasoning step, the trivial cleanup step. The easy steps don't need a frontier model. You're paying Opus-4.8 prices to decide whether a message is a question or a complaint.

agentcents shows you, per step, what you pay and what you could pay — then routes each step to the cheapest model that clears the bar. In a typical 7-step task:

all-Opus-4.8 $0.114 → cost-routed $0.055 — 51% cheaper, keeping the flagship only where the work demands it.

---

How it works

A local proxy sits between your agent and the LLM provider. You point at it; it does the rest — identifies each task (no tagging required), prices it against every current model, checks capability, and shows you the plan.

your agent  →  agentcents (localhost:8082)  →  any LLM provider

1. pip install agentcents — Python ≥ 3.9
2. agentcents start — the local proxy comes up on port 8082
3. Point your client at it (one base URL, or wrap your run — see below)
4. agentcents usage — see exactly where every cent went

---

Forecast, calibrate, orchestrate — the trust ladder

Cost tools that auto-route on day one are asking you to trust an estimator you've never seen graded. agentcents does it in the order an engineer would:

1 · Forecast. agentcents explain prices a request on every candidate model before it runs. The parts that can be measured are measured (your prompt's tokens, known cache state); the part that can't — how much the model will say — is an honest p50 → p90 range learned from your own traffic, never a falsely precise point.

$ echo '{"model":"gpt-4o","messages":[...]}' | agentcents explain --tag whatsapp

CANDIDATE              TOTAL p50→p90            note
ollama/local           $0.000015 → $0.000018    ← pick · util 12%
openai/gpt-4o-mini     $0.000294 → $0.000498
openai/gpt-4o          $0.004900 → $0.008300    requested

2 · Calibrate. Every call through the proxy silently logs its forecast next to the actual. The /explain calibration page — and agentcents explain --accuracy — grade the estimator in public: p90 coverage against its 90% target, q-error against 1.00, one candle per call on the calibration strip. You watch the forecasts earn their keep on your workload, not a benchmark.

3 · Orchestrate. The /orchestrator page shows the plan-chooser's per-node decisions, each passing five gates: robustness (a swap binds only if it's cheapest across the whole forecast range), a quality floor (never route below the node's capability bar), tool-use and provider-boundary safety, and the trust gate — binding requires the calibration page to prove the forecasts first. Advisory today, by design. The switch flips when the evidence does.

---

Two Cents — the neutral cost guide

Every dashboard page carries ✦ two cents: ask about your spend, your calibration, your tags, or how anything on screen works, in plain language.

What makes it different from the AI assistant in every other tool:

• It runs on your hardware by default. Local-first: it picks a model from your own Ollama installation, answers for fractions of a cent of electricity, and shows you the cost of each answer — metered in your own ledger, subject to your own budgets, like any other agent.
• It isn't selling tokens. A cloud vendor's chatbot will never tell you to use the free local model. Two Cents will, because that's often the right answer. Cloud fallback exists but only among models you've actually used and hold a key for — never a catalog — and always with a billing warning.
• It sees aggregates, never prompts. Spend summaries, calibration stats, what's on your screen. Your prompt contents are not stored and not shared.
• Its memory is yours. Conversation memory lives in your local ledger, compressed over time by your own local model, and survives switching to any LLM.

---

Quick start

Zero-config — wrap your run:

agentcents run -- python my_agent.py

agentcents sets the base URLs, groups the run into one session, and gets out of the way. Your agent code is untouched.

Or one env var:

export OPENAI_BASE_URL="http://localhost:8082/openai"
python my_agent.py

Or one line in code:

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8082/openai")
# everything else stays exactly the same

Already setting your own session or tag headers? agentcents recognizes the common ones (X-Session-ID, X-Request-ID, and more) automatically. The proxy adapts to your client — never the other way around.

---

What the proxy does

It doesn't just log. It advises.

• Cost, before you spend. A request's cost on every candidate model as an honest range — fresh input, cached input, cache writes, output — never a false point estimate.
• Cheapest capable model, not just cheapest. Every candidate is ranked by a real capability score (Artificial Analysis Intelligence Index) alongside its price, so the advice is "cheapest model that clears this step's bar," never "cheapest, quality be damned."
• Accuracy you can inspect. Predicted vs actual on every call, graded on the calibration page. Routing goes binding only after the numbers hold.
• Current models. Prices and capability sync from the providers and public leaderboards — Opus 4.8, Fable 5, GPT-5.6, Sonnet 5, Gemini — not last year's lineup.
• Your whole task as a plan. agentcents reconstructs the multi-step plan your agent actually ran and shows the cost of each node — like a query plan, for LLM calls.
• Local as a first-class option. Running Ollama? It's priced in (power cost, not $0), so you see exactly when local beats the cloud and when it doesn't.

---

CLI

$ agentcents usage
─────────────────────────────────
Total spend (last 48h)   $3.42
  my-agent          $2.10   61%
  research-agent    $1.32   39%
─────────────────────────────────
Daily budget             $5.00
Remaining                $1.58

$ agentcents explain --accuracy
  MODEL                  TAG        N   p90 cov   q-err med
  ollama/gpt-oss:20b     my-agent  212      92%       1.18
  overall: p90 coverage 92% (target ~90%), median q-error 1.18

Other commands: agentcents explain (pipe a request in), agentcents models, agentcents sync, agentcents agents, agentcents rolling, agentcents local, agentcents features.

---

Supported providers

Anything that speaks the OpenAI or Anthropic format: OpenAI, Anthropic, Google Gemini, OpenRouter, Groq, and local Ollama. Pricing syncs automatically on proxy startup from public catalogs, with current frontier prices carried in a bundled config the aggregators lag on.

---

Free vs Pro

Free forever — no account needed:

• Proxy + cost logging (cache-aware, cost-accurate)
• Cost forecasts (agentcents explain) + calibration page
• Two Cents guide — local-first, ~$0 per answer
• Exact-match cache
• Budget alerts + hard block
• Full CLI reporting
• Web dashboard (light + dark) · plan · orchestrator showcase
• Local Ollama tracking

Pro — one-time license (agentcents activate <key>):

• Everything in Free
• Advisor + routing on your own traffic (which cheaper models actually clear the bar on your workload, learned from your real calls)
• Semantic similarity cache
• Multi-agent TUI dashboard + live call watch
• Auto-routing (swap mode)
• XGBoost cost predictor

For Pro dependencies: pip install 'agentcents[pro]'.

Get Pro: https://labhamfounder.gumroad.com/l/agentcents-pro

---

License

agentcents is proprietary software, © Labham LLC. All rights reserved. The source is distributed for transparency and inspection; use is licensed, not sold. See LICENSE.txt for terms. Pro features require a valid license key.

Contact: [e-mail] · https://labham.com