🛰 agent-control-plane

The systems layer around an agent — not another agent.

Anyone can wire up a model and some tools. What decides whether it survives production is the layer around it: a portable tool surface, scope grants the model cannot argue with, failure modes you can name and detect, and a bill you can predict before it arrives.

git clone https://github.com/sujithnsn953/agent-control-plane
cd agent-control-plane
python examples/demo.py     # all four, ~0.1s, no API key
pytest                      # 55 tests

Zero runtime dependencies — the MCP server, both transports and the HTTP conformance tests are standard library only. There is no framework between the code and the spec.

Three things, each enforced in code

1. A spec-correct MCP server — protocol 2025-11-25

Not a wrapper around someone else's SDK. JSON-RPC 2.0 framing, lifecycle, and both standard transports, written against the spec's MUSTs with a conformance test for each rule that is easy to get wrong:

Two decisions worth defending:

Version negotiation doesn't echo. If a client requests a version we don't speak, the server replies with its own latest rather than parroting the request back. Echoing claims support you don't have, and the client finds out the hard way.

Tool failure is a result, not a protocol error. A tool that raises returns isError: true so the model can see it and adapt. JSON-RPC errors are reserved for protocol faults — which keeps "the agent misbehaved" separable from "the transport did".

2. Orchestration with failure modes that are detected, not described

A supervisor plans and delegates. Workers hold scoped tool grants. A critic reviews. The supervisor holds no tools at all — so a confused supervisor wastes tokens rather than causing side effects, and every side effect traces to exactly one scoped worker.

Seven named pathologies, each detectable as a pure function of the run record, each driven deliberately in test_failure_modes.py:

critic_deadlock is the one I'd read first. Bounding the loop stops the budget bleeding, but a run that exits early because the synthesis stopped changing is still a run whose reviewer never accepted the answer. Flagging only on the round limit would hide exactly the case the bound was added to handle — so the detector covers both.

3. Cost governance — the question that separates shipped from demoed

Hiring guides put it bluntly: someone who has never reasoned about inference cost has never shipped under a budget.

routing 8/10 calls down: $0.0738 vs $0.225 always-frontier  (67.2% saved)
prefix reused  1x    : caching LOSES money  (breakeven at 1.278 calls)
prefix reused  2x    : worth caching
per-run P&L          : $0.044500 of $0.5 ceiling
  supervisor:synthesis     $0.042500
  reader:t1                $0.002000

Prompt-cache breakeven is independent of prefix size. Writing to cache costs more than a normal input token; reading costs far less. Set the two totals equal and the prefix length cancels:

N* = (cache_write − cache_read) / (input − cache_read)

So "is my prompt big enough to cache?" is the wrong question. "Will I reuse it enough times?" is the right one — and for a prefix you touch once, caching is a straight loss. There's a test for that.

Routing escalates on evidence, never on a guess — a declared complexity or an actual failure — and every decision records why. A routing layer you can't audit is one nobody will trust with production traffic.

The ceiling is enforced, not advisory. charge() raises when the budget is gone, and a rejected charge is never recorded — a ledger that logs charges it refuses can't be reconciled against the provider's bill.

Related MCP server: production-grade-mcp-agentic-system

How this fits the other two repos

This is the platform; those are its components.

• secure-rag-assistant — a prompt instruction is not a security control: redaction before embedding, scope filtering before ranking, 39 security tests.

• pharma-ops-agent — a correct final answer is not a working agent: trajectory evaluation, budgets, loop detection, and a CI release gate.

• pharma-supply-intelligence — the data platform underneath: Event Hubs → Databricks medallion → XGBoost → FastAPI, Terraform-provisioned and run live on Azure.

Three focused libraries and one platform composing them, which is how real teams build — and a better signal than one repo trying to do everything.

Roadmap

Phase 1 is what's here. Next: OpenTelemetry GenAI tracing, working/episodic memory with write policies, hybrid retrieval (BM25 + vector) with recall@k, and a human-in-the-loop approval queue with a kill switch for irreversible actions.

A note on the numbers

Model prices move constantly. The table in pricing.py is illustrative and configurable — verify_prices_before_use exists so nobody ships a cost model built on a stale constant. The arithmetic is the durable part; the rates are data you supply.

License

MIT — see LICENSE.