How to add a spend ceiling to an OpenAI agent

PythonNode.jsOpenAI

OpenAI's usage limits fire after the fact. AgentBill adds a preflight check — the run is blocked before the first API call if the budget says so.

Why not just use OpenAI's spend limits?

OpenAI's account-level limits are monthly caps — they don't protect you from a single expensive run. AgentBill enforces a ceiling per invocation, per customer, before the run starts. If the estimated units exceed your ceiling, the call is blocked with no tokens consumed.

Install

pip install agentbill-sdk openai

Add a preflight check to any OpenAI call

from openai import OpenAI
from agentbill import AgentBillClient

# ceiling=100: block any run estimated at more than 100 units
agentbill = AgentBillClient(api_key="agb_your_key", ceiling=100)
openai_client = OpenAI()

def run_agent(customer_id: str, task: str) -> str:
    # Block before any OpenAI tokens are consumed
    check = agentbill.preflight(
        agent_id="openai_assistant",
        estimated_units=10,
        customer_id=customer_id
    )
    if not check.approved:
        return {"error": "budget_exceeded", "reason": check.reason}

    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": task}]
    )

    agentbill.record(
        agent_id="openai_assistant",
        units=10,
        customer_id=customer_id
    )
    return response.choices[0].message.content

Use the @gate decorator

The @client.gate() decorator wraps the function with preflight + record automatically.

from openai import OpenAI
from agentbill import AgentBillClient

agentbill = AgentBillClient(api_key="agb_your_key", ceiling=100)
openai_client = OpenAI()

@agentbill.gate(agent_id="openai_assistant", estimated_units=10, customer_id="user_123")
def run_agent(task: str) -> str:
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": task}]
    )
    return response.choices[0].message.content

Handle blocking errors

from agentbill import AgentBillClient, BudgetExhaustedError, CeilingExceededError

try:
    result = run_agent("user_123", "summarize this document")
except CeilingExceededError:
    return {"error": "run exceeds per-request ceiling"}
except BudgetExhaustedError:
    return {"error": "customer budget exhausted"}

Node.js

import OpenAI from 'openai'
import { AgentBillClient } from 'agentbill'

const openai = new OpenAI()
const agentbill = new AgentBillClient({ apiKey: 'agb_your_key', ceiling: 100 })

async function runAgent(customerId: string, task: string): Promise<string> {
  const check = await agentbill.preflight({
    agentId: 'openai_assistant',
    estimatedUnits: 10,
    customerId
  })
  if (!check.approved) throw new Error(check.reason)

  const res = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: task }]
  })

  await agentbill.record({ agentId: 'openai_assistant', units: 10, customerId })
  return res.choices[0].message.content ?? ''
}

Get your API key — free tier, no credit card