> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Metrics

> Track tokens, cost, requests, tool calls, and timing across every model call this agent participates in.

## Overview

Every agent exposes a single read-only **`agent.usage`** property. It returns an `AggregatedUsage` view derived from the [centralized usage registry](/concepts/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

```python theme={null}
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

<Note>
  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) |
</Note>

## Related Documentation

* [Usage Registry](/concepts/usage-registry) — Architecture, scope tags, persistence
* [Task Metrics](/concepts/tasks/metrics) — Per-task scoped view
* [Chat Metrics](/concepts/chat/metrics) — Per-session scoped view
* [Team Metrics](/concepts/team/metrics) — Per-team scoped view


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.