> ## 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 your Agent's token usage, timing, and costs across all runs

## Overview

Your **Agent** keeps a single **`usage`** object (`AgentUsage`) that accumulates metrics over every run. Use it to monitor total tokens, requests, tool calls, cost, and detailed timing breakdowns for that agent.

For a quick, JSON-friendly snapshot of session spend, you can also use **`agent.cost`** — a dictionary that aggregates the same token and cost figures across every task the agent has executed. See [Quick Session Summary via `agent.cost`](#quick-session-summary-via-agent-cost) below.

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

On any `Agent` instance, use **`agent.usage`**. It returns an `AgentUsage` object (or `None` before the first run).

### 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_write_tokens` | `int` | Total tokens written to the cache                       |
| `cache_read_tokens`  | `int` | Total tokens read from the cache                        |
| `reasoning_tokens`   | `int` | Total tokens used for reasoning (e.g. chain-of-thought) |

### 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 \| None` | Total execution time across all runs (seconds)                                         |
| `model_execution_time`   | `float \| None` | Total time spent inside LLM API calls (seconds)                                        |
| `tool_execution_time`    | `float \| None` | Total time spent executing tools across all runs (seconds)                             |
| `upsonic_execution_time` | `float \| None` | Framework overhead = `duration - model_execution_time - tool_execution_time` (seconds) |

### Cost Metrics

| Property | Type            | Description                                              |
| -------- | --------------- | -------------------------------------------------------- |
| `cost`   | `float \| None` | Estimated total cost across all runs (provider-specific) |

## Quick Session Summary via `agent.cost`

`agent.cost` is a convenience property that returns a single dictionary aggregating tokens and estimated cost across **every** task the agent has executed (`do`, `do_async`, `run`, `run_async`). It's especially useful for autonomous agents and prebuilt agents that dispatch several tasks per run — bootstrap, workspace setup, the user's prompt, sub-agents — so the dictionary reports the full session spend, not just the last task.

* Returns **`None`** before any task has been executed.
* Returns a `dict[str, Any]` once the agent has run at least one task.
* `estimated_cost` is in USD and is `None` when the model's pricing cannot be resolved.

| Key                  | 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`           | `input_tokens + output_tokens`                                    |
| `estimated_cost`     | `float \| None` | Estimated total cost in USD (or `None` if pricing not resolvable) |
| `requests`           | `int`           | Total number of LLM API requests                                  |
| `tool_calls`         | `int`           | Total number of tool calls executed                               |
| `cache_read_tokens`  | `int`           | Total tokens read from cache                                      |
| `cache_write_tokens` | `int`           | Total tokens written to cache                                     |
| `reasoning_tokens`   | `int`           | Total reasoning/chain-of-thought tokens                           |

```python theme={null}
from upsonic import Agent, Task

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

summary = agent.cost
# {
#   'input_tokens': 184,
#   'output_tokens': 10,
#   'total_tokens': 194,
#   'estimated_cost': 0.000702,
#   'requests': 2,
#   'tool_calls': 0,
#   'cache_read_tokens': 0,
#   'cache_write_tokens': 0,
#   'reasoning_tokens': 0,
# }

print(f"Spent ${summary['estimated_cost']:.4f} over {summary['requests']} requests")
```

<Note>
  `agent.cost` and `agent.usage` are **complementary, not duplicative**. `agent.usage` is the full `AgentUsage` object with timing breakdowns (`duration`, `model_execution_time`, etc.); `agent.cost` is a flat dictionary focused on tokens and money — convenient for logging, dashboards, or returning over an API.
</Note>

## 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}")
print(f"Cost:            ${u.cost:.4f}")
print(f"Duration:        {u.duration:.2f}s")
print(f"Model time:      {u.model_execution_time:.2f}s")
if u.tool_execution_time is not None:
    print(f"Tool time:       {u.tool_execution_time:.2f}s")
print(f"Framework time:  {u.upsonic_execution_time:.2f}s")
```

## 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                 │
╰───────────────────────────────────────────────────────╯
```

## Accumulation Behavior

* **Across tasks**: Every call to `do` / `print_do` / `do_async` / `print_do_async` adds to the same `agent.usage`. The `AgentUsage` object accumulates each task's `TaskUsage` via its `incr()` method.
* **Sub-agent propagation**: When an agent uses another agent as a tool, the sub-agent's usage (tokens, requests, tool calls, cost, timing) is propagated into the parent agent's `usage`.
* **Independent agents**: Each `Agent` instance has its own independent `AgentUsage`. Two different agents never share usage.