Inspect AI requests and usage

Inspect a saved request

AI calls save requests by default. Use the returned aiRequestId to query AiRequest through ActiveRecord. Request records include status, input, response, error information, duration and provider-reported token usage.

Agent runs save a root request and a child for each provider attempt. Provider calls made by tools are linked below the active attempt. This lets you inspect what happened without losing failed attempts or counting aggregate usage twice.

import { AiRequest } from '@db3.ai/app/ai';

const request = await AiRequest.findByPk(aiRequestId);
console.log(request?.status, request?.inputTokens, request?.outputTokens);

Account for the complete run

AiRequest.runCostSummary(id) walks the request tree and returns token totals, provider request count, known cost and the number of unpriced requests. Provider-reported costs take precedence where supported; otherwise the framework uses its model pricing table.

Missing usage or unknown pricing must not be treated as free work. totalCostUSD is a known subtotal when unpricedRequestCount is nonzero. Keep price tables current and reconcile commercial billing with your provider’s records.

const usage = await AiRequest.runCostSummary(aiRequestId);
console.log(usage?.providerRequestCount, usage?.totalTokens);
console.log(usage?.totalCostUSD, usage?.unpricedRequestCount);

Apply your application’s allowance policy

Configure ai.allowance to check user or workspace budget before provider work. The callback receives the provider, operation, model, scope and pending request where available. Throw AIAllowanceExceededError to reject the operation.

Provider rate limits and customer credits answer different questions. The framework tracks work and exposes policy hooks; your app defines subscriptions, prices, credit buckets and an idempotent ledger. Agent subclasses can override usageCharge() and settleUsage() for that policy. Nested operations should be attributed to their parent run instead of creating another root charge.

Test without live provider calls

Inject fetch through your App’s AI options with a synthetic key. Keep the real Agent runtime, SDK, database and Storage in the test; replace only the external provider response. Use a disposable database and run the same app migrations used at boot.

The framework integration tests exercise function calls, history reload, ownership rejection, queued reconstruction, nested request parentage, text failover, structured output, image storage and embeddings. The generated app tests its Notes route with simulated AI responses. These tests establish the app contract, not the quality or availability of a live model.

• Test your generated app