Agent cost controls

LLM-driven agents can consume budget unboundedly if a single user message triggers an infinite tool-call loop, or if a long-running conversation crosses a cost ceiling you only want to hit once. Orbit gates every agent run on three independent ceilings, all configurable per agent.

The three ceilings

Ceiling	Scope	Default	What triggers it
`max_cost_per_run_cents`	One `chat` / `invoke` / `chat-stream` call (one user turn → one assistant turn, including tool-call iterations).	`$1.00` platform default when unset (per-agent only — no org/env fallback)	Aggregated cost across all LLM calls within a single run, computed from per-model token rates.
`max_cost_per_conversation_cents`	The lifetime of a single `agent_conversations.id` — every run that touches the same conversation row.	unbounded (falls back to the org/env cap — see precedence below)	Probed before every LLM iteration, including iteration 0, so a conversation that hit the cap on a previous turn is also blocked on the next turn.
`tool_loop_limit`	Tool-call loop iterations within one run (the per-turn tool-iteration loop guard).	10 (bounds 1..50)	Counts each tool-call loop iteration. The run-wide hard envelope of 50 LLM API calls (`AGENT_MAX_API_CALLS_PER_RUN`) is always enforced on top of this.

Both cost caps accept 0–10000 cents ($0–$100); 10000 cents ($100) is the maximum — setting either field higher returns a 400 validation error. See Semantics for the full value table. When any ceiling is exceeded the agent emits a final error event and stops:

{ "type": "error", "code": "COST_LIMIT", "message": "Cost budget exceeded" }

The corresponding codes are COST_LIMIT (per-run cost), CONVERSATION_COST_CAP_REACHED (per-conversation cost), API_CALL_LIMIT (per-run LLM-call cap), TOKEN_LIMIT (per-conversation token aggregate), and TOOL_ITERATION_LIMIT (tool-loop guard).

Configure on agent create

curl -X POST https://api.orbit.devotel.io/api/v1/agents \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "model": "claude-sonnet-4-6",
    "system_prompt": "You are a customer support agent for Acme Corp.",
    "max_cost_per_run_cents": 25,
    "max_cost_per_conversation_cents": 500,
    "tool_loop_limit": 10
  }'

tool_loop_limit is the per-agent tool-iteration knob (bounds 1..50, default 10). It is persisted under config.tool_loop_limit; when unset it falls back to the platform default of 10. The run-wide hard envelope of 50 LLM API calls (AGENT_MAX_API_CALLS_PER_RUN) is always enforced on top of it and cannot be raised by agent config.

Configure on agent update

curl -X PUT https://api.orbit.devotel.io/api/v1/agents/agent_abc123 \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "max_cost_per_run_cents": 25,
    "max_cost_per_conversation_cents": 500
  }'

Both fields are persisted under config.max_cost_per_run_cents / config.max_cost_per_conversation_cents on the agent row.

Semantics

Both max_cost_per_run_cents and max_cost_per_conversation_cents accept a whole number of USD cents in the range 0–10000 ($0–$100). 10000 cents ($100) is the maximum accepted value — a request that sets either field above it is rejected with a 400 validation error before the agent is created or updated. This input ceiling is independent of the platform hard cap that silently clamps the resolved per-conversation value (see below).

Value	Meaning
Positive integer	The cap (in USD cents), from `1` to `10000` (`$100` max — higher values return a `400` validation error). Run / conversation aborts when accumulated cost exceeds this value.
`null` (or omitted)	Falls back to the platform default. For `max_cost_per_conversation_cents` the org/env cap still applies (see precedence below); for `max_cost_per_run_cents` there is no org/env fallback — an unset per-run cap falls back to the platform default of `$1.00` per run (it is not unbounded). Set the field explicitly to raise or lower that ceiling.
`0`	Kill switch. Blocks ALL spend immediately — first LLM call fails with `COST_LIMIT`. Useful when you want to disable an agent without deleting it.

How accumulated cost is computed

Per-run: real-time accumulation across the streaming loop. Estimated from prompt + completion tokens at the model’s per-1K rate, plus a flat per-API-call overhead.
Per-conversation: tracked in Redis under a key keyed off agent_conversations.id. Each run debits the counter on completion; the next run’s iteration-0 probe reads the counter and refuses if it’s already over the cap.
The counter is reset only by deleting the conversation. Re-using a conversation_id after the cap will keep failing until you provision a fresh one.

Which cap participates in the org/env precedence chain

Only the per-conversation cap resolves through a fallback chain. The runtime calls resolveCostCapCents and takes the first non-null value (an explicit 0 kill-switch wins over a null further down):

Per-agent — agents.config.max_cost_per_conversation_cents
Per-org — organizations.settings.agent_runtime_cost_cap_cents
Platform default — the DEVOTEL_AGENT_COST_CAP_CENTS_DEFAULT env var

The per-run cap (max_cost_per_run_cents) is a per-agent-only knob with no org or env fallback. The runtime enforces it directly off the agent definition (accumulated run cost >= the cap → COST_LIMIT); if you leave it unset on the agent it falls back to the platform default of $1.00 per run (not unbounded), regardless of any org-level or env-level setting. To allow more than $1.00 of spend in a single run, set max_cost_per_run_cents explicitly. There is no agent_runtime_cost_cap_cents equivalent for per-run spend.

A platform hard cap clamps the resolved per-conversation value — regardless of source. After the chain above resolves, the runtime applies DEVOTEL_LLM_PER_CONVERSATION_MAX_USD (see Platform budget governors, default **

5 / 500 cents**) as a final ceiling. Any resolved value **above** the hard cap — including an explicit per-agent `max_cost_per_conversation_cents` — is silently lowered to it; a resolved `null` (unbounded) inherits it. This means a per-agent cap you set through the API can be enforced at a *lower* number than you configured. To let a per-conversation cap above

5 take effect, an operator must raise DEVOTEL_LLM_PER_CONVERSATION_MAX_USD (or set it to 0 to disable the ceiling); no agent- or org-level setting can lift it.

Per-conversation token ceiling

In addition to the cost caps above, every conversation is bounded by an aggregate token ceiling. When the running token total for a conversation crosses this value the agent terminates gracefully and the run ends with a TOKEN_LIMIT error code. This guards against runaway loops where token usage grows non-linearly with context length even when the per-token cost is cheap.

Setting	Scope	Default	Overridable
`max_tokens_per_conversation`	Aggregate tokens across the lifetime of a single conversation.	`10000`	Yes — per agent.

The 10000 default is a deliberately conservative back-compat value, not a hard platform cap. Set max_tokens_per_conversation on the agent (create or update) to raise (or lower) it — for example 50000 for long support resolutions or multi-step workflows. Send null to clear an override back to the default. When raising it, also raise max_cost_per_run_cents / max_cost_per_conversation_cents accordingly, since the tenant-configurable spend cap remains the primary ceiling.

curl -X PUT https://api.orbit.devotel.io/api/v1/agents/agent_abc123 \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "max_tokens_per_conversation": 50000 }'

It is persisted under config.max_tokens_per_conversation on the agent row; values must be a whole number of tokens between 1 and 1000000.

Hard platform ceilings (always enforced)

These are floor / ceiling values that no agent config can override:

Limit	Value
`AGENT_MAX_API_CALLS_PER_RUN`	50
`MAX_TOOL_ITERATIONS_HARD_CEILING`	50

They exist to prevent runaway behaviour even when an agent’s per-run cap is set to a high value. MAX_TOOL_ITERATIONS_HARD_CEILING (50) is the absolute ceiling on tool_loop_limit — a per-agent override is clamped to this and cannot exceed it. The platform default of 10 (when tool_loop_limit is unset) is not a hard ceiling: it is the overridable starting value described in the tool_loop_limit knob above.

Platform budget governors (operator-facing)

The per-agent / per-conversation knobs above are tenant-configurable via the agents API. Underneath them sit platform-level spend and rate governors set by environment variable (defaults in packages/shared/src/env.ts, overridden per cluster via Secret Manager). These are the values an SRE greps when paged for a platform-wide 503 LlmPlatformCeilingExceeded or a tenant 429 RATE_LIMIT_EXCEEDED (scope: tenant_tpm). They are listed in .env.example under the LLM budget / cost governors block.

Env var	Default	Scope	What it does
`DEVOTEL_LLM_BUDGET_DEFAULT_MONTHLY_USD`	`200`	Per tenant	Default monthly LLM spend budget — long-horizon spend governor.
`DEVOTEL_LLM_BUDGET_DEFAULT_DAILY_USD`	`20`	Per tenant	Default daily LLM spend budget. Pairs with the monthly cap; both gates fire, whichever exceeds first wins. Defends the “burn the whole month in 6h” runaway pattern.
`DEVOTEL_LLM_BUDGET_PLATFORM_MONTHLY_CEILING_USD`	`10000`	All tenants	Hard aggregate monthly ceiling across every tenant. When summed all-tenant monthly spend would exceed this, the gateway raises `LlmPlatformCeilingExceeded` (503) platform-wide and fires a Sentry alert. Set `0` to disable (not recommended).
`DEVOTEL_LLM_PER_CONVERSATION_MAX_USD`	`5`	Per conversation	Hard cap on per-conversation LLM cost (USD).
`DEVOTEL_LLM_PER_CONVERSATION_MAX_ITERATIONS`	`12`	Per conversation	Per-conversation tool/LLM iteration cap (minimum `1`).
`DEVOTEL_LLM_TPM_PER_TENANT`	`200000`	Per tenant	Tokens-per-minute sliding-window breaker. Rejects any new Anthropic call that would push the tenant’s 60s token sum past this cap with a 429 `RATE_LIMIT_EXCEEDED` + `Retry-After: 60`. Default mirrors Anthropic’s Tier-2 TPM floor. Set `0` to disable (not recommended).

DEVOTEL_LLM_BUDGET_PLATFORM_MONTHLY_CEILING_USD is a hard 503 gate across ALL tenants — when it trips, every tenant’s agent traffic stops, not just the offending one. Raise it (or investigate the runaway tenant) before clearing the page; do not set it to 0 to silence an incident.

Observability

Cost-cap enforcement is observable through logs and metrics, not webhooks — there is no subscribable cost-cap webhook event. Every per-conversation cap fire emits a structured warn log line from the agent runtime carrying a metric field you can alert on:

{
  "level": "warn",
  "metric": "agent.conversation_cost_cap_hit",
  "tenantId": "org_abc123",
  "conversationId": "conv_def456",
  "currentCents": 514,
  "capCents": 500,
  "msg": "Conversation cost cap reached — refusing further agent runs"
}

Alert on the agent.conversation_cost_cap_hit metric to catch runs that hit the cap. Clients also receive the final error event with the matching code (COST_LIMIT, CONVERSATION_COST_CAP_REACHED, API_CALL_LIMIT, TOKEN_LIMIT, or TOOL_ITERATION_LIMIT) on the aborted run. There is no agent.run.aborted webhook — do not subscribe for one.

Recommended starting values

Tier-1 customer support agent — max_cost_per_run_cents=25, max_cost_per_conversation_cents=500.
Voice agent (longer turns, STT/TTS overhead) — max_cost_per_run_cents=50, max_cost_per_conversation_cents=1000.
Internal QA / sandbox — max_cost_per_run_cents=10, max_cost_per_conversation_cents=50 to catch loops fast.

The voice-agent max_cost_per_conversation_cents=1000 (

10) above **exceeds the default

5 platform hard cap** (DEVOTEL_LLM_PER_CONVERSATION_MAX_USD). Unless an operator raises that env var, the effective per-conversation ceiling is silently halved to $5 — see the precedence-chain warning. Confirm the platform value is set to at least your intended cap before relying on it.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

Agent cost controls

Agent cost controls

The three ceilings

Configure on agent create

Configure on agent update

Semantics

How accumulated cost is computed

Which cap participates in the org/env precedence chain

Per-conversation token ceiling

Hard platform ceilings (always enforced)

Platform budget governors (operator-facing)

Observability

Recommended starting values

See also

​Agent cost controls

​The three ceilings

​Configure on agent create

​Configure on agent update

​Semantics

​How accumulated cost is computed

​Which cap participates in the org/env precedence chain

​Per-conversation token ceiling

​Hard platform ceilings (always enforced)

​Platform budget governors (operator-facing)

​Observability

​Recommended starting values

​See also

Agent cost controls

The three ceilings

Configure on agent create

Configure on agent update

Semantics

How accumulated cost is computed

Which cap participates in the org/env precedence chain

Per-conversation token ceiling

Hard platform ceilings (always enforced)

Platform budget governors (operator-facing)

Observability

Recommended starting values

See also