DEV Community

Sathish Chelliah
Sathish Chelliah

Posted on

Inside agent-gov: Architecture of an Agent Cost Governance Platform

#ai #python #opensource #architecture

Inside agent-gov: Architecture of an Agent Cost Governance Platform

AI agents orchestrate complex workflows — calling LLMs, scraping pages, querying databases, sending emails. Each call costs real money. Without a governance layer, a single buggy loop can burn through your budget before anyone notices.

agent-gov is an open-source reverse proxy that intercepts every tool call your agents make, enforces budgets in real time, and auto-pauses out-of-control agents. Built as a FastAPI service with SQLite persistence, running 45 tests in 0.3 seconds.

This post walks through the architecture: the proxy pattern, the four-stage decision tree, cost tracking with a tool registry, multi-tenancy via workspaces, and the lazy auto-reset pattern.

The Proxy Pattern

Every AI agent tool call passes through agent-gov before reaching the actual tool. The agent sends a POST /proxy/call with its API key, tool name, and estimated cost. agent-gov validates, budgets, and logs — then returns a 200 to approve or a 429 to reject.

class ToolCall(BaseModel):
    agent_key: str = Field(...)
    tool_name: str = Field(...)
    estimated_cost: float = Field(0.0, ge=0)
Enter fullscreen mode Exit fullscreen mode

The proxy doesn't execute the tool itself — it guards access. The agent only proceeds if the proxy returns 200. This is the gatekeeper pattern: a lightweight decision layer between the agent and the outside world.

Agent -> POST /proxy/call -> agent-gov -> 200/429 -> Agent decides
                                                      |
                                                 Calls actual tool
                                                      |
                                                      v
                                               OpenAI / Browser / API
Enter fullscreen mode Exit fullscreen mode

Why a proxy instead of a library? A library can be monkey-patched, removed, or forgotten. A proxy is a network boundary that agents must cross — it can't be bypassed.

The Decision Tree: Auth -> Check -> Budget -> Log

Every proxy call runs through a four-stage pipeline:

@app.post("/proxy/call")
async def proxy_tool_call(call: ToolCall):
    key_hash = db.hash_key(call.agent_key)
    agent = await db.get_agent(key_hash)

    # Step 1: Auth
    if agent is None:
        raise HTTPException(status_code=401, detail="Invalid API key")

    # Step 2: Paused check
    if agent["paused"]:
        raise HTTPException(status_code=429,
            detail=f"Agent '{agent['name']}' is paused.")

    # Step 3: Auto-reset budget if new day
    agent = await db.check_and_reset_budget(agent)

    # Step 4: Look up REAL tool cost
    registered_tool = await db.get_tool(call.tool_name)
    actual_cost = (registered_tool["cost_per_call"]
                   if registered_tool else call.estimated_cost)

    # Step 5: Budget check
    new_total = agent["spent_today"] + actual_cost
    if new_total > agent["daily_budget"]:
        await db.pause_agent(key_hash)
        raise HTTPException(status_code=429,
            detail="Budget exceeded — agent auto-paused.")

    # Step 6: Approved — update spend and log
    updated = await db.update_agent_spend(key_hash, actual_cost)
    await db.log_cost_event(key_hash, agent["name"], call.tool_name, actual_cost)
    return {"status": "approved", ...}
Enter fullscreen mode Exit fullscreen mode
Stage Check Exit
Auth Does the API key hash match? 401 — Invalid key
Pause Is the agent paused? 429 — Agent paused
Reset New day since last call? (silent)
Budget Would this exceed the daily cap? 429 + auto-pause
Log INSERT cost event 200 — Approved

Cost Tracking: Registry vs. Estimate

The trickiest design decision was cost determination. Trusting the agent's estimated_cost is fragile — agents can under-report.

agent-gov uses a tool registry: an UPSERT-able table of known tools with real per-call costs.

registered_tool = await db.get_tool(call.tool_name)
actual_cost = (registered_tool["cost_per_call"]
               if registered_tool else call.estimated_cost)
Enter fullscreen mode Exit fullscreen mode

If the tool is registered, its true cost is used. The response includes a cost_source field so clients know which path was taken.

The test proves an agent can't lie its way past governance: an agent with a $100 budget claiming a $1 estimate for a tool registered at $500/call gets blocked with 429.

Multi-Tenancy: Workspace Isolation

v0.5 introduced workspaces — isolated tenants with their own agents, tools, and cost events. Each workspace gets a unique ID and API key. Every database row carries a workspace_id FK column.

Schema migration uses PRAGMA table_info to add columns only when missing — SQLite doesn't support IF NOT EXISTS for ALTER TABLE.

Tests verify workspace isolation: two workspaces, agents in each, neither can see the other's data.

The Auto-Reset Pattern: Lazy Daily Budgets

Instead of a midnight cron job creating a thundering herd, agent-gov uses lazy evaluation: every proxy call checks if a reset is needed.

async def check_and_reset_budget(agent: dict) -> dict:
    today = date.today().isoformat()
    if agent["last_reset"] == today:
        return agent
    if agent["paused"]:
        return agent
    return await reset_daily_budget(agent["key_hash"])
Enter fullscreen mode Exit fullscreen mode

An agent that makes no calls doesn't need a reset. The thundering herd becomes a gentle trickle.

What's Next

The next evolution: per-tool budget caps, webhook-based alerts, and a management API. But the foundation — a simple, testable, async governance proxy — is solid.

agent-gov is open source and MIT licensed. 45 tests. Zero database setup.

Top comments (0)