Agent Metrics

Overview

Every agent exposes a single read-only agent.usage property. It returns an AggregatedUsage view derived from the centralized usage registry on each access, scoped to this agent’s agent_usage_id. Sub-pipeline model calls — memory summarization, reliability validator/editor, culture, policy, and sub-agents invoked as tools — automatically inherit the agent’s scope and roll into agent.usage without any manual propagation. When printing is enabled (print_do / print_do_async), an Agent Metrics panel is displayed after each task so you can see the updated totals.

Accessing Agent Metrics

Read agent.usage on any Agent instance. It always returns an AggregatedUsage — zero-valued before the first run, populated thereafter.

Token Metrics

Property	Type	Description
`input_tokens`	`int`	Total prompt/input tokens across all runs
`output_tokens`	`int`	Total completion/output tokens across all runs
`total_tokens`	`int`	Sum of `input_tokens + output_tokens`
`cache_read_tokens`	`int`	Tokens read from prompt cache
`cache_write_tokens`	`int`	Tokens written to prompt cache
`reasoning_tokens`	`int`	Reasoning (chain-of-thought) tokens

Request & Tool Metrics

Property	Type	Description
`requests`	`int`	Total number of LLM API requests made
`tool_calls`	`int`	Total number of tool calls executed

Timing Metrics

Property	Type	Description
`duration`	`float`	Sum of per-call durations across contributing entries (seconds)
`model_execution_time`	`float`	Total time spent inside LLM API calls (seconds)
`tool_execution_time`	`float`	Total time spent executing tools (seconds)
`upsonic_execution_time`	`float`	Framework overhead = `duration − model − tool` (seconds)
`time_to_first_token`	`float \| None`	Earliest TTFT across contributing entries

Cost Metrics

Property	Type	Description
`cost`	`float \| None`	Sum of `cost_usd` across contributing entries. `None` if no entry was priced; `0.0` means priced and free.

Aggregation Metadata

Property	Type	Description
`entry_count`	`int`	Number of underlying `UsageEntry` rows contributing to this view
`models`	`list[str]`	Distinct model identifiers that contributed (first-seen order)

Example

from upsonic import Agent, Task

agent = Agent("anthropic/claude-sonnet-4-5", print=True)
agent.print_do(Task("What is 2 + 2? Reply with one number."))
agent.print_do(Task("What is 3 + 3? Reply with one number."))

u = agent.usage

print(f"Requests:        {u.requests}")
print(f"Input tokens:    {u.input_tokens}")
print(f"Output tokens:   {u.output_tokens}")
print(f"Tool calls:      {u.tool_calls}")
if u.cost is not None:
    print(f"Cost:            ${u.cost:.4f}")
print(f"Model time:      {u.model_execution_time:.2f}s")
print(f"Tool time:       {u.tool_execution_time:.2f}s")
print(f"Framework time:  {u.upsonic_execution_time:.2f}s")
print(f"Models used:     {u.models}")

Printed Panel

When you use print_do or print_do_async, the Agent Metrics panel displays after each task:

╭──────────────────── Agent Metrics ────────────────────╮
│  Agent:                  MyAgent                      │
│                                                       │
│  Total Requests:         4                            │
│  Total Input Tokens:     1,552                        │
│  Total Output Tokens:    915                          │
│  Total Tool Calls:       2                            │
│  Total Estimated Cost:   $0.0008                      │
│  Total Duration:         21.55 seconds                │
│  Model Execution Time:   18.17 seconds                │
│  Tool Execution Time:    1.00 seconds                 │
│  Framework Overhead:     2.38 seconds                 │
╰───────────────────────────────────────────────────────╯

Scope & Propagation

Across tasks — Every call to do / print_do / do_async / print_do_async records entries against the agent’s scope. Reading agent.usage re-aggregates them, so the figures always reflect the latest state.
Sub-pipeline rollup — Memory summarization, reliability validator/editor, culture, policy, and sub-agent calls inherit the parent’s scope via context variables and roll into agent.usage automatically.
Retry idempotency — The registry is keyed by entry_id. Retried requests replace their prior entry instead of double-counting.
Independent agents — Each Agent instance has its own agent_usage_id. Two different agents never share usage.
JSON snapshot — Call agent.usage.to_dict() for a flat dict suitable for logs and dashboards.

Legacy Migration

Legacy surfaces have been removed in favour of agent.usage:

Legacy	Replacement
`agent.cost` (dict)	`agent.usage.to_dict()`
`AgentUsage.incr()` / accumulator fields	(registry-derived; no mutation needed)
`agent._finalize_agent_usage`, retry baseline machinery	(registry is idempotent)

Usage Registry — Architecture, scope tags, persistence
Task Metrics — Per-task scoped view
Chat Metrics — Per-session scoped view
Team Metrics — Per-team scoped view

GET STARTED

CONCEPTS

STARTING AN AGENT PROJECT

READY TO USE SNIPPETS

DEPLOYMENT

FURTHER READINGS

Overview

Accessing Agent Metrics

Token Metrics

Request & Tool Metrics

Timing Metrics

Cost Metrics

Aggregation Metadata

Example

Printed Panel

Scope & Propagation

Legacy Migration

​Overview

​Accessing Agent Metrics

​Token Metrics

​Request & Tool Metrics

​Timing Metrics

​Cost Metrics

​Aggregation Metadata

​Example

​Printed Panel

​Scope & Propagation

​Legacy Migration

​Related Documentation

Overview

Accessing Agent Metrics

Token Metrics

Request & Tool Metrics

Timing Metrics

Cost Metrics

Aggregation Metadata

Example

Printed Panel

Scope & Propagation

Legacy Migration

Related Documentation