Cost and tracing patterns

Use traces to understand what ran, evaluations to check whether it was correct, and cost accounting to estimate reported usage. These answer different questions. The quality-gate project provides a complete runnable application that retains reports and JSONL traces.

Observe one run and estimate its cost

Host function: pass a configured model, its current per-1,000-token prices, and the input. Install matching @agentium/core and @agentium/observability, plus the selected provider dependency. The function owns the Agent and observer; a live provider makes a real request.

import { Agent, CostTracker, type ModelPricing, type ModelProvider } from "@agentium/core";
import { instrument } from "@agentium/observability";

export async function runObserved(model: ModelProvider, pricing: ModelPricing, input: string) {
  const cost = new CostTracker({ pricing: { [model.modelId]: pricing } });
  const agent = new Agent({ name: "observed-support", model, register: false, costTracker: cost });
  const observation = instrument(agent, { exporters: ["console"], metrics: true });
  try {
    const result = await agent.run(input);
    if (result.status !== "completed") throw new Error(`Observed run: ${result.status}`);
    return {
      text: result.text,
      usage: result.usage,
      estimate: cost.getSummary(),
      metrics: observation.metrics?.getMetrics(),
    };
  } finally {
    try { await agent.close(); } finally { await observation.shutdown(); }
  }
}

Expect a console trace and a return value containing reported tokens, the cost estimate, and metrics. Default tracing excludes prompt, tool, and output content. If the model reports no usage, do not interpret a zero estimate as a free request. The explicit price key follows model.modelId, so changing models does not accidentally retain the previous model’s lookup key. The caller must update the values too. The v4 bundled price table predates the current text models in these docs.

Supply matching prices

ModelPricing uses dollars per 1,000 tokens. Prices listed per million must be divided by 1,000. For example, the standard uncached text rates checked on October 4, 2026 were:

Model	`promptPer1k`	`completionPer1k`
`gpt-6.1-sol`	`0.002`	`0.01`
`gpt-6-luna`	`0.0001`	`0.0005`

These are dated example rates from the OpenAI model catalog. Recheck your provider, model, service tier, caching, and audio/reasoning billing when adapting them. See example model choices and the pricing type.

Add a budget with the right expectation

Configuration factory: the caller attaches this tracker to the Agent(s) it wants to account for. The model ID and prices must match those executions.

import { CostTracker, type ModelPricing } from "@agentium/core";

export function createBudget(modelId: string, pricing: ModelPricing) {
  return new CostTracker({
    pricing: { [modelId]: pricing },
    budget: {
      maxCostPerRun: 0.10,
      maxTokensPerRun: 8_000,
      onBudgetExceeded: "throw",
    },
  });
}

Budget checks use known usage at their execution boundaries. They cannot retract a request already accepted by a provider or guarantee a maximum invoice. Use model output limits, bounded tool rounds, host concurrency, and provider controls as well. See cost auto-stop for in-progress checks. When sharing a tracker, use stable user/session identifiers and choose the lifetime of accumulated entries deliberately. An in-memory tracker is not your billing ledger.

Choose an evidence destination

Need	Guide	Verify
Inspect a local run	Console exporter	A settled trace appears
Retain CI artifacts	Quality-gate project	Report and JSONL files exist, including failing runs
Export OTLP/HTTP JSON	OpenTelemetry	Collector protocol and receipt
Use a host-owned tracer	OTel bridge in the same guide	Parent context and host SDK lifecycle
Send to Langfuse	Langfuse exporter	Credentials, endpoint, and trace delivery
Scrape metrics	Metrics export	Expected series and labels

Delivery through a bounded exporter is not an authoritative audit ledger. Flush owned telemetry after active runs and Agent cleanup settle; the host owns shutdown of borrowed exporters or SDK providers according to their contract.

More patterns

Use exporter selection for all destinations, capture settings for bounded content capture, evaluation patterns for answer quality, and operations for limits and drain.

Complete projects

Agents & memory

Models & Jev

Tools & knowledge

Teams & jobs

Deploy & devices

Quality & production

Cost and tracing patterns

Observe one run and estimate its cost

Supply matching prices

Add a budget with the right expectation

Choose an evidence destination

More patterns

​Observe one run and estimate its cost

​Supply matching prices

​Add a budget with the right expectation

​Choose an evidence destination

​More patterns

Observe one run and estimate its cost

Supply matching prices

Add a budget with the right expectation

Choose an evidence destination

More patterns