Configuration
Common environment and monitor() knobs for the public Control path.
monitor() essentials
Section titled “monitor() essentials”| 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.
Connect Agent FinOps (Control)
Section titled “Connect Agent FinOps (Control)”| 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_MULTIPLIERis set (PricingConfigErrorotherwise). 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 OpenAIfrom 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.
When Agent FinOps is unreachable
Section titled “When Agent FinOps is unreachable”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).
Latency
Section titled “Latency”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.
Pause an organization
Section titled “Pause an organization”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
BudgetExceededbefore the provider is called; - the deny receipt names the pause (
determining_constraint.policy_idstarts withorg_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.
Model pricing and unknown models
Section titled “Model pricing and unknown models”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 |
Content capture
Section titled “Content capture”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.
One budget across several clients
Section titled “One budget across several clients”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 clientsbudget.remaining_usd # headroom, including calls in flightA 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.
When the provider refuses a call
Section titled “When the provider refuses a call”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.
