Skip to main content

context.usage

Agent usage tracking for context monitoring.

Tracks token usage, message history, and tool calls for agents to provide real-time context usage information.

UsageCategory Objects​

@dataclass
class UsageCategory()

A category of usage with a name and token value.

to_dict​

def to_dict() -> dict[str, Any]

Convert to dictionary format for API response.

RequestUsage Objects​

@dataclass
class RequestUsage()

Usage for a single request/response cycle.

AgentUsageStats Objects​

@dataclass
class AgentUsageStats()

Usage statistics for a single agent.

total_tokens​

@property
def total_tokens() -> int

Total tokens used (input + output).

message_tokens​

@property
def message_tokens() -> int

Total tokens in messages.

update_from_run_usage​

def update_from_run_usage(input_tokens: int = 0,
                          output_tokens: int = 0,
                          cache_read_tokens: int = 0,
                          cache_write_tokens: int = 0,
                          requests: int = 0,
                          tool_calls: int = 0,
                          tool_names: list[str] | None = None,
                          duration_ms: float = 0.0) -> None

Update usage stats from a run result.

update_message_tokens​

def update_message_tokens(user_tokens: int = 0,
                          assistant_tokens: int = 0) -> None

Update message token counts.

set_system_prompt_tokens​

def set_system_prompt_tokens(tokens: int) -> None

Set system prompt token count.

store_messages​

def store_messages(messages: list[Any]) -> None

Store message history from an agent run.

Converts pydantic-ai ModelMessage objects to JSON-serializable dicts. Replaces the current message history (messages accumulate in the agent).

Arguments:

  • messages - List of pydantic-ai ModelMessage objects.

store_tools​

def store_tools(
        tool_definitions: list[tuple[str, str | None, dict[str,
                                                           Any]]]) -> None

Store tool definitions from an agent run.

Arguments:

  • tool_definitions - List of (name, description, params_schema) tuples.

reset​

def reset() -> None

Reset all usage statistics.

AgentUsageTracker Objects​

class AgentUsageTracker()

Global tracker for agent usage statistics.

Maintains usage stats for all registered agents and provides context details for the frontend.

DEFAULT_CONTEXT_WINDOW​

128K tokens (common for modern models)

__init__​

def __init__() -> None

Initialize the usage tracker.

register_agent​

def register_agent(agent_id: str, model: str | None = None) -> AgentUsageStats

Register an agent for usage tracking.

Arguments:

  • agent_id - Unique identifier for the agent.
  • model - Optional model name for context window calculation.

Returns:

The usage stats object for the agent.

unregister_agent​

def unregister_agent(agent_id: str) -> None

Remove an agent from usage tracking.

get_agent_stats​

def get_agent_stats(agent_id: str) -> AgentUsageStats | None

Get usage stats for an agent.

get_or_create_stats​

def get_or_create_stats(agent_id: str) -> AgentUsageStats

Get or create usage stats for an agent.

get_context_window​

def get_context_window(agent_id: str) -> int

Get the context window size for an agent.

set_model​

def set_model(agent_id: str, model: str) -> None

Set the model for an agent (affects context window calculation).

update_usage​

def update_usage(agent_id: str,
                 input_tokens: int = 0,
                 output_tokens: int = 0,
                 cache_read_tokens: int = 0,
                 cache_write_tokens: int = 0,
                 requests: int = 0,
                 tool_calls: int = 0,
                 tool_names: list[str] | None = None,
                 duration_ms: float = 0.0) -> None

Update usage statistics for an agent.

Arguments:

  • agent_id - The agent identifier.
  • input_tokens - Number of input tokens used.
  • output_tokens - Number of output tokens used.
  • cache_read_tokens - Number of tokens read from cache.
  • cache_write_tokens - Number of tokens written to cache.
  • requests - Number of API requests made.
  • tool_calls - Number of tool calls executed.
  • tool_names - List of tool names used in this request.

get_context_details​

def get_context_details(agent_id: str) -> dict[str, Any]

Get context usage details for an agent.

Returns a structured breakdown of context usage suitable for the frontend ContextUsage component.

Arguments:

  • agent_id - The agent identifier.

Returns:

Dictionary with context usage details.

list_agents​

def list_agents() -> list[str]

List all tracked agent IDs.

reset_agent​

def reset_agent(agent_id: str) -> None

Reset usage statistics for an agent.

get_usage_tracker​

def get_usage_tracker() -> AgentUsageTracker

Get the global usage tracker instance.