Skip to main content

monitoring.llm_context_usage

LLM context usage tracking capability for pydantic-ai lifecycle hooks.

Centralises per-run token usage collection that was previously duplicated across every adapter (PydanticAI, Vercel AI, AG-UI). The capability hooks into before_run / after_run so usage is recorded consistently regardless of which transport or adapter is in use.

Tracked data:

  • Input / output / cache-read / cache-write tokens
  • Request count and tool call count (with tool names)
  • Per-request usage history with timestamps and durations
  • Message-level token estimates (user / assistant)
  • Serialised message history (for context snapshot rebuilds)

LLMContextUsageCapability Objects​

@dataclass
class LLMContextUsageCapability(AbstractCapability[Any])

Record per-run LLM token usage into the shared UsageTracker.

This replaces the manual tracker.update_usage(…) calls that were scattered through every adapter's run / stream method.

Parameters​

agent_id : str Agent identifier used as storage key in the usage tracker. enabled : bool Master switch — when False the hooks are no-ops.