Guides
Worked Example

Worked Example

This example meters an agent run for tenant acme, blocks overspend, and later reports cost by step.

Create a tenant budget

Budget::create([
    'name' => 'Acme daily cap',
    'scope_type' => 'tenant',
    'scope_id' => 'acme',
    'limit_amount' => 50,
    'currency' => 'USD',
    'period' => 'daily',
    'soft_limit_pct' => 80,
    'hard' => true,
]);

Attach context

app(TraceContext::class)->within([
    'tenant_id' => 'acme',
    'cost_center' => 'support',
    'trace_id' => 'ticket-4832',
    'agent_step' => 'classify',
    'purpose' => 'customer-support',
], fn () => $agent->respond($prompt));

Read the trace

curl /api/ai-finops/usage/ticket-4832/trace

Report the tenant
```
php artisan ai-finops:report --days=1
```

Expected ledger shape

Rows include provider, model, tokens, cost_method, tokens_estimated, billed_cost, billed_currency, frozen price source, tenant, cost center, trace id, and agent step.

Do not use zero for unknown price

If a model has no price and cannot be estimated, return an unknown or null result. A zero cost means covered, not unknown.

Last updated: Edit this page