Interface: LlmUsageEvent

Defined in: packages/agentos/src/api/observers.ts:44

Payload delivered to a registered usage observer once an LLM call resolves. Mirrors the agentos-side fields that downstream cost / billing systems care about.

Properties

finishReason?

optional finishReason: string

Defined in: packages/agentos/src/api/observers.ts:65

Mirrors the finishReason on the GenerateText result so observers can distinguish a clean stop from a token-cap truncation.

---

model

model: string

Defined in: packages/agentos/src/api/observers.ts:48

Resolved model id (e.g. 'gpt-4o', 'claude-sonnet-4-6').

---

provider

provider: string

Defined in: packages/agentos/src/api/observers.ts:46

Resolved provider id (e.g. 'openai', 'anthropic', 'openrouter').

---

source?

optional source: string

Defined in: packages/agentos/src/api/observers.ts:60

Opt-in source label set by the caller via the source option (e.g. 'narrator_turn', 'companion_reply', 'world_compile_job'). Hosts use this to tag emitted rows with their own meter_key.

---

surface

surface: "generateImage" | "generateText" | "generateObject" | "streamText" | "streamObject" | "embedText"

Defined in: packages/agentos/src/api/observers.ts:71

Which agentos surface fired the event. Lets a single observer route generateText, generateObject, generateImage, embedText, etc. into different meters when needed.

---

usage

usage: TokenUsage

Defined in: packages/agentos/src/api/observers.ts:54

Aggregated token usage for the call — promptTokens, completionTokens, totalTokens, costUSD, cacheReadTokens, cacheCreationTokens. Mirrors the usage field on the GenerateText/Object result.