Skip to content

Configuration

Common environment and monitor() knobs for the public Control path.

Argument / concern Notes
max_budget_usd Local hard cap used for pre-dispatch deny (this client only)
budget A SharedBudget that several clients draw from; use instead of max_budget_usd
stream_cutoff_usd Optional local cutoff based on observable streamed output; not authoritative settlement
agent_id Agent identity for evidence
Attribution fields See Attribution
allow_unmetered Paid endpoints outside Control (for example ("/embeddings",)) that may be sent without a budget check; that spend is not counted
loop_guard What a request that repeats like a loop does: its words overlap one of the same customer’s last 32 on this client by more than 85% (90% on async clients), or it sends the same tools list a third time. Each customer (business_subject_ref) has its own history, up to 64 per client; calls naming no customer share one. "record" (default, 1.2.3 and later) writes a finops.loop.anomaly event ("reason": "repeated_request") and sends the call. "block" raises LoopDetected before dispatch (the default up to 1.2.2). "off" skips the check

stream_enforcement is deprecated. Use stream_cutoff_usd when an additional best-effort in-stream guard is required. Pre-dispatch reservation remains the authoritative concurrency-safe spending boundary.

Variable Notes
KAZENAI_FINOPS_URL Your Agent FinOps URL. Setting it (or KAZENAI_FINOPS_INGEST_URL) selects the Control lifecycle
KAZENAI_FINOPS_API_KEY An SDK key from Agent FinOps
KAZENAI_TIER_MISMATCH_MULTIPLIER Required under Control. A finite number of at least 1
KAZENAI_DEPLOYMENT_MODE production or staging for deployed services. In both, the FinOps URL must be public https:// (no private, loopback or link-local address, also after DNS), and monitor() refuses anything else
KAZENAI_FINOPS_RESERVE_TIMEOUT_S Timeout for one attempt of a pre-call reservation: 2 s by default in 1.2.1 and later (0.8 s before), including connection setup. A reservation that gets no answer is sent once more with the same idempotency key, so it is never reserved twice
KAZENAI_REQUIRE_CUSTOMER_ID LiteLLM callback only: 1 refuses a call that names no customer with HTTP 400
KAZENAI_GATEWAY_PENDING_DIR LiteLLM callback only: where unsent settlements are kept (default ~/.kazenai/gateway-pending)
KAZENAI_GATEWAY_FLUSH_INTERVAL_S LiteLLM callback only: how often later traffic resends unsent settlements (default 30)
KAZENAI_FINOPS_KEEPALIVE_S Seconds an idle connection to Agent FinOps is kept for reuse (default 15); 0 opens a new connection per request
KAZENAI_SDK_SETTLE_QUEUE_DIR Persistent private directory for pending settlements
KAZENAI_SDK_SETTLE_AUTO_FLUSH 0 turns off the in-process settlement flusher
KAZENAI_SETTLE_IN_BACKGROUND 1.2.4 and later: 0 sends the settle after a call before the response returns, as up to 1.2.3. By default it is journaled to disk, then sent in the background; Agent FinOps holds the reserved amount until it lands, so the limit is never weaker
KAZENAI_SETTLE_EXIT_WAIT_S 1.2.4 and later: seconds the process waits at exit for settles still being sent (default 2); what isn’t sent stays journaled for the flusher
KAZENAI_PRICING_LIVE 0 turns off the signed live price catalog (the bundled snapshot still applies)
KAZENAI_ENDPOINT_PRICE_MULTIPLIERS Exact-host map (values >= 1) for proxies that bill at list price; other non-first-party hosts are priced at 1.1x

With a FinOps URL set, every guarded call reserves against your limits in Agent FinOps before it is sent and settles after it returns. A refused reservation raises BudgetExceeded, and the provider is never called.

monitor() refuses to start under Control unless:

  • KAZENAI_TIER_MISMATCH_MULTIPLIER is set (PricingConfigError otherwise). When a provider bills a call at a service tier KazenAI has no certified price for, KazenAI holds the requested-tier price times this number against the limit and keeps the call for reconciliation. Use at least the price ratio of the most expensive tier your provider can apply.
  • the provider client is built with max_retries=0 (UnsupportedModeError, unsupported_provider_retries, otherwise). Each retry is a new billable attempt, so KazenAI reserves for each one itself.
from openai import OpenAI
from kazenai import monitor
client = monitor(
OpenAI(max_retries=0),
agent_id="support-agent",
org_id="<organization ID>", # both IDs are on the Setup page in Agent FinOps
workspace_id="<workspace ID>",
max_budget_usd=5.00,
)

An Agent FinOps API key belongs to one organization and one workspace, and monitor() must name the same two with org_id and workspace_id. The Setup page in Agent FinOps shows both and fills them into its code snippet. monitor() does not read them from the key or from KAZENAI_ORG_ID. Without them it uses local and default, Agent FinOps refuses each reservation with HTTP 403, and the call raises BudgetUnavailable before it reaches the provider.

KAZENAI_PROFILE=legacy selects the pre-1.2 check/reconcile path. It is deprecated, warns, and is removed in 2.0; hosted Agent FinOps refuses it with HTTP 501.

By default Control fails closed: if the SDK cannot reach Agent FinOps, the call is refused (BudgetUnavailable) and nothing is sent to the provider.

An org admin can choose fail-open instead, in Agent FinOps on the Policy page (“When Agent FinOps can’t be reached”), or with PUT /v1/org/{org_id}/failure-policy and a reason (limits:write, recent sign-in; audited). With fail-open, a call the SDK cannot reserve still runs, limited only by the SDK’s local caps (max_budget_usd):

  • It applies only when Agent FinOps does not answer: no connection, a timeout, or HTTP 408, 429 or 5xx. An over-limit call, a paused organization, a tier breaker or an invalid key is always refused.
  • Calls let through this way are not charged to the organization’s limits in Agent FinOps. The SDK logs a warning (at most one a minute per organization) with the number of calls.
  • The SDK learns the setting from Agent FinOps before each reservation (cached for 30 seconds) and keeps the last value on disk next to the settlement queue (KAZENAI_SDK_SETTLE_QUEUE_DIR). A process that has never seen the setting fails closed.
  • The LiteLLM gateway callback always fails closed.

KAZENAI_ENFORCEMENT_MODE=fail_open in the environment is ignored except in explicit local development (KAZENAI_ENV=dev).

From 1.2.4, a guarded call makes one request to Agent FinOps before the provider call: the reserve, which also records that the call may start. The settle after the answer is sent in the background, so your response doesn’t wait for it. The time added to each call is about one network round trip to Agent FinOps plus its processing: a few milliseconds when your app runs in the same cloud region, and about 75 ms more at 75 ms away. Run your app close to Agent FinOps. Up to 1.2.3, or with an Agent FinOps that doesn’t offer start-on-admit, it is three requests in a row (the reserve, provider_started and usage_known).

In a short-lived process (a serverless handler), call kazenai.spine.guard.drain_settlements() before returning. A process frozen before the settle is sent keeps the reservation held until Agent FinOps’s recovery (15 minutes), then marks it outcome unknown: never an overspend, but the budget looks used until it is reconciled. KAZENAI_FINOPS_KEEPALIVE_S (default 15 seconds) is how long an idle connection is kept; it stays below common NAT and firewall idle timeouts.

An admin (limits:write, recent sign-in) can pause an organization in Agent FinOps, from the Policy page or with POST /v1/org/{org_id}/pause and a reason. While it is paused:

  • every new reservation for that organization is refused with HTTP 402, which the SDK raises as BudgetExceeded before the provider is called;
  • the deny receipt names the pause (determining_constraint.policy_id starts with org_pause:) without exposing the operator’s reason;
  • calls already admitted still settle or cancel.

The pause has no expiry. Resume with POST /v1/org/{org_id}/resume or from the Policy page. Both actions are audited.

The pre-dispatch bound needs a price. kazenai ships one pricing table, checked against the providers’ official pricing pages on the date in kazenai.model_pricing.PRICING_LAST_VERIFIED, covering current OpenAI, Anthropic, Gemini, and DeepSeek models. Dated snapshots of a priced model (for example claude-haiku-4-5-20251001) resolve to it; a different version (for example gpt-5.3) does not borrow a sibling’s price.

From 1.1.2, a model with no price is blocked before dispatch in every environment (UnknownModelError), so it can never count as $0 against a budget. To use such a model:

Option How
Add its price KAZENAI_PRICING_JSON='{"my-model":{"input_per_1k":0.002,"output_per_1k":0.008}}'
Pass a rate monitor(..., usd_per_1k_tokens=0.01)
Conservative estimate KAZENAI_UNKNOWN_MODEL_POLICY=estimate
Report $0 and log (development only) KAZENAI_UNKNOWN_MODEL_POLICY=warn — ignored in production-like deployments

Default capture is metadata-only (no prompts, completions, or tool argument bodies). Enabling content capture requires explicit configuration and must follow consent, authorization, and retention rules. See Security and privacy.

Each monitor(..., max_budget_usd=...) client enforces its own cap. A workflow whose steps use different models or providers usually has one client per provider, so those caps add up. Share one cap instead:

from kazenai import SharedBudget, monitor
budget = SharedBudget(max_usd=1.00)
openai_client = monitor(OpenAI(max_retries=0), budget=budget)
anthropic_client = monitor(Anthropic(max_retries=0), budget=budget)
budget.spent_usd # total across both clients
budget.remaining_usd # headroom, including calls in flight

A call on any of these clients is denied before dispatch (BudgetExceeded) when its estimate no longer fits the shared remaining budget. SharedBudget covers one process; across processes or machines, give every client the same workflow_id and set a workflow limit in Agent FinOps.

If the provider rejects a request outright (HTTP 4xx such as bad request, invalid key, model not found, or rate limited), nothing was generated: the reservation settles at exactly $0 and the hold is released. Timeouts, dropped connections and 5xx errors stay pending for reconciliation, because the provider may have done the work.