AgentBill

A preflight gate for AI agent runs. Stop runaway loops before they start.

Budget exceeded? GPU quota hit? Free tier exhausted? AgentBill blocks the run before the first token, not after the damage is done.

Works whether you're paying OpenAI per token or running your own GPU.

$ python run_agent.py

[AgentBill] preflight check... BLOCKED
  reason: free_tier_exceeded (1000/1000 calls used)
  upgrade: https://agentbill.dev/upgrade

Agent did not run. $0 spent.

vs. without AgentBill:

$ python run_agent.py

[OpenAI] Running research loop...
... 3 hours later ...
[OpenAI] $47.82 charged

"The moment you're using Stripe as your safety net, you've already lost the run." scarlett1908, r/LangChain

Install

Python:

pip install agentbill-sdk

Node.js:

npm install agentbill

Related MCP server: circle-agent-stack-mcp

Quick Start

from agentbill import AgentBillClient, BudgetExhaustedError

client = AgentBillClient(api_key="agb_your_key", ceiling=50)  # max units for one run

try:
    client.preflight(agent_id="researcher", customer_id="cust_abc", estimated_units=10)
except BudgetExhaustedError:
    ...  # customer is out of budget. Nothing ran. $0 spent.

# run your agent here

client.record(agent_id="researcher", customer_id="cust_abc", units=10)

Blocks raise: BudgetExhaustedError, CeilingExceededError, TaskCeilingExceededError, FreeTierExceededError, PlanLimitExceededError.

Get your API key: https://agentbill.dev/register

What it does

Preflight. Before the agent runs, AgentBill checks: does this customer have enough budget? If not, block it before any compute is consumed.

Per-request ceiling. Monthly caps do not catch the bad single run. One 3-hour research loop can blow your budget before the cap triggers. AgentBill enforces a ceiling at the invocation level.

Per-task ceiling. One job spans many calls across several models and tools. Pass task_ref with a task_ceiling on the first call and AgentBill enforces one hard budget for the whole job, not per call.

Outcome-based metering. You define what counts as a billable event. Not bytes, not seconds. The business-level action the agent performed.

Pricing

A call is one POST /preflight. The counter resets on the 1st of each calendar month. When you run out, the block response carries the upgrade_url, so your agent never needs a browser.

When to use AgentBill

• Add billing to a LangChain agent. Wrap any chain with preflight() + record(). Two calls.

• Per-request spend ceiling for OpenAI agents. Set a ceiling per invocation, not just a monthly cap.

• Preflight budget check before an LLM run. Block the run before any tokens are consumed.

• Agent cost control in Python or Node.js. SDK available for both.

• Usage-based billing for your AI SaaS. Charge customers per agent run, not per seat.

What it does NOT do

• Multi-step workflows with state machines or reversal logic (out of scope)

• Replace your payment processor (AgentBill sits in front of it)

• No-code dashboard for non-developers

Why not Stripe

MCP Server

AgentBill ships an MCP server for native integration with Claude Code, Cursor, Windsurf, and any MCP-compatible agent host.

uvx agentbill-mcp

The MCP server exposes two tools:

• preflight(agent_id, customer_id, estimated_units, ceiling). Check budget before running. Blocks if exhausted.

• record_event(agent_id, units, customer_id, metadata). Bill after work completes.

Configure in ~/.claude/settings.json:

{
  "mcpServers": {
    "agentbill": {
      "command": "uvx",
      "args": ["agentbill-mcp"],
      "env": { "AGENTBILL_API_KEY": "agb_..." }
    }
  }
}

Source: mcp/ | PyPI: agentbill-mcp

Tech Stack

Local Dev

Prerequisites: Node.js 20+, Python 3.10+

git clone https://github.com/marketinglior-pixel/agentbill.git
cd agentbill
npm install
cp .env.example .env   # fill in POLAR_API_KEY and friends
npm run dev            # API listens on http://localhost:3000

Run the smoke test suite (requires the dev server running):

./test_live.sh

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup instructions, code style, and how to open a PR.

Looking for something to work on? Check the good first issue label.

Star this repo

If per-request ceilings are what you needed, star this. It helps other developers find it.