Set and inspect agent cost limits

Use a policy budget to check estimated model cost before a supported call and record available usage afterwards. Start with a preview, then compare its estimate with the observed result of a small run.

Before you begin

Choose a workspace with an explicit model, current pricing and an effective block-mode policy. Check the integration's supported controls with actspan verify; a configuration field alone does not establish enforcement. Budgets govern model-cost estimates and observations, not the monetary value of a refund or other business action.

Model-free allowed and denied probe

This procedure was exercised on October 22, 2026 with the public Apple Silicon 0.2.0 executable (SHA-256 02bd46192b7a85d52c6bc74879e628a8f78907337a491dccacb2bb709918ceb5). Use a fresh copy of the quickstart's two files. Keep its hello prompt, model gpt-4.1-mini, output limit 128 and block-mode policy. No live provider key is needed for these local probes.

Save model_pricing.csv alongside them, using USD per-token rates:

provider,model,in_usd_per_tok,out_usd_per_tok,effective_date
openai,gpt-4.1-mini,0.0000004,0.0000016,2026-10-22

These standard text rates correspond to $0.40/$1.60 per million input/output tokens; see the provider model reference. They do not include hosted tools or account-specific discounts. Add pricing_csv: ./model_pricing.csv to the existing exec object and this block to the existing hello_policy entry, preserving its other restrictions:

budget:
  max_cost_per_run_usd: 0.01

Then run only the model-free verifier:

export OPENAI_API_KEY="<public-docs-offline-placeholder>"
actspan verify workspace.yaml hello --no-portal --format json

Expected: the allowed baseline reaches the pre-dispatch boundary; the synthetic budget violation is refused with PER_RUN_EXCEEDED before dispatch. The probe also violates the output-token restriction, so check the budget reason itself, not merely any denial. This rehearsal produced five passed checks, one unsupported provider-allowlist probe, no failed/unverified checks, and exit 2 for incomplete coverage. That exit is expected scope, not a complete verification pass. No provider request or sandbox write is made.

Restore your real key only before a deliberately selected live request. Keep the explicit catalog with the report so a packaged or workspace-local historical catalog cannot silently change the estimate. See pricing units.

Add budget fields to another selected policy

This policy entry illustrates a native Claude Messages request:

enabled: true
policies:
  - name: claude_costs
    version: "1.0"
    provider: anthropic
    resource: messages
    operation: create
    admission:
      mode: block
    budget:
      max_cost_per_run_usd: 0.20
      max_daily_cost_usd: 2.00
    limits:
      max_output_tokens: 400

Merge this into the policy catalog selected by the workspace; do not remove its existing tool/model rules. Bind the policy using the workspace's existing exec.policy_file, environment and policy-selection settings. A budget entry that is not selected does not govern a run. See the complete refund workspace for a policy already wired to execution.

Preview before spending

actspan validate workspace.yaml
actspan preview workspace.yaml --admission block --strict-schema --no-portal --format json

Preview makes no provider call. Inspect the selected model, pricing match, estimated cost and would_block result. The native pre-call check can refuse a call whose estimate reaches its configured per-run threshold, or would exceed the daily total visible to that runtime's ledger. Default admission can be warn; use an effective block-mode policy when refusal is required.

Expected result: preview identifies the selected model and policy, reports the available estimate and shows whether the configured block-mode check would refuse it. Resolve unknown pricing before treating that estimate as coverage.

Pricing resolves from exec.pricing_csv, ACTSPAN_PRICING_CSV, a workspace data/model_pricing.csv, then the packaged catalog. Supply the model's real rates and review unknown pricing. A missing estimate or usage field is not proof of zero cost. Output-token limits help bound a request, but estimates can differ from actual billing, especially across retries and tool continuations.

Claude Haiku 5.5 uses prompt-length pricing tiers. The current catalog's flat input/output columns cannot represent those tiers and intentionally leave that model unpriced. A single manual CSV rate cannot reproduce the tiered behavior. Review the official model pricing and use a model with supported, reviewed pricing when relying on these estimates.

Compare recorded usage

After a deliberately small live run, inspect its result:

actspan inspect "RUN_ID" --json

Compare available token usage, model identity, estimated/actual cost and policy violations. Supported native paths also evaluate available post-run cost/token outcomes. Post-run refusal cannot undo a provider charge or a tool side effect. Reconcile with provider billing when accounting accuracy matters.

Understand the enforcement boundary

• These checks do not reserve a shared daily allowance atomically across concurrent workers, machines or different ledgers.
• A field named max_cost_per_run_usd does not establish a cumulative hard cap over every workflow node, hidden SDK retry or external tool charge.
• Available pricing and usage determine cost visibility. Cached, failed or provider-specific calls can leave incomplete evidence.
• LangChain callbacks use observed/estimated costs and do not advertise atomic hard-budget enforcement. Mandatory unsupported coverage is refused rather than established by callback installation.

Use provider-account limits and a credential-owning enforcement boundary when you need an independent spending restriction. Keep their actual guarantees separate from Actspan's policy estimates and recorded evidence.