Budget Enforcement

Budget enforcement prevents runaway agents from burning through your API spend. Set a dollar cap per run, and Papayya checks budget before each step and stops when exceeded.

How it works

You set budget_usd on your agent config (or budget_cents via the API)
After every LLM call, Papayya calculates the cost based on token count and model pricing
If total cost exceeds the budget, the run transitions to budget_exceeded status
No more steps are executed

How enforcement works in the runtime

When your @agent function runs in a Papayya container, the runtime shim intercepts every LLM call (OpenAI, Anthropic, etc.) transparently:

Before each LLM call — the shim reserves worst-case cost against the run's budget via the control plane. If the reservation would exceed the budget, the call is aborted before hitting the provider.
After each LLM call — the shim reports the actual token count and cost, releasing the reservation and committing the real cost.
If budget is exceeded — the run transitions to paused with a budget_exceeded status. No more LLM calls execute.

This means a single LLM call can still bring the total slightly over budget (the actual cost may exceed the reservation), but the overshoot is bounded to one call's cost.

Integer math

Cloud runs store budgets and costs in cents (integers) to avoid floating-point drift. When you set budget_usd: 1.00 in the SDK, it becomes budget_cents: 100 internally.

This matters for long-running agents that accumulate many small costs — floating-point addition can drift over hundreds of steps, but integer math stays exact.

Infinite loop detection

Beyond budgets, Papayya has a heuristic for detecting infinite loops — agents that keep calling the same tool with the same input repeatedly. When detected, the run is stopped and marked as failed.

Setting budgets

In the SDK

Python

from papayya import agent
 
@agent(name="my-agent", model="gpt-4o-mini", budget_usd=2.00, max_steps=50)
def my_agent(input_data):
    ...

TypeScript

const agent = new Agent({
  name: "my-agent",
  model: myClient,                          // your own ModelClient (BYOF)
  model_label: "claude-sonnet-4-20250514",  // optional dashboard label
  instructions: "...",
  max_steps: 50,
  budget_usd: 2.00,  // $2.00 cap per run
  tools: [],
});

Via the CLI (scheduled runs)

papayya schedule create \
  --agent-id ag_abc123 \
  --cron "0 9 * * *" \
  --budget-cents 500  # $5.00 per scheduled run

Via the API

POST /v1/runs
{
  "agent_id": "ag_abc123",
  "input": "...",
  "budget_cents": 200
}

Choosing a budget

A few rules of thumb:

Simple tasks (< 10 steps, Sonnet): $0.10–$0.50
Research tasks (10–30 steps, Sonnet): $0.50–$2.00
Complex workflows (30–100 steps, Opus): $5.00–$20.00

Start conservative and increase based on actual usage you observe in the dashboard.

Durability Replay