Token Tracking

Read real token spend from any agent — no flags, no setup

Every agent records its token usage; read the running total whenever you need it.

Token accounting is on for every agent that runs through the native OpenAI path — the default when you pass a bare model name like "gpt-4o-mini". You don’t turn it on, you just read it back.

Quick Start

1. Run an agent and read the total

   A bare Agent(llm="gpt-4o-mini") records its usage automatically. Read it back with the global collector:

   from praisonaiagents import Agent
   from praisonaiagents.telemetry.token_collector import get_token_collector
   
   agent = Agent(llm="gpt-4o-mini")
   agent.start("Summarise the theory of relativity in one paragraph")
   
   summary = get_token_collector().get_session_summary()
   print(summary["total_interactions"])
   print(summary["total_metrics"]["input_tokens"])
   print(summary["total_metrics"]["output_tokens"])

   The numbers are real spend — no metrics=True, no verbose, no display flag required.

2. Break usage down per agent

   Pass a name to each agent and the collector rolls usage up under by_agent:

   from praisonaiagents import Agent
   from praisonaiagents.telemetry.token_collector import get_token_collector
   
   researcher = Agent(name="researcher", llm="gpt-4o-mini")
   writer = Agent(name="writer", llm="gpt-4o-mini")
   
   researcher.start("Find three facts about the Moon")
   writer.start("Write a haiku about the Moon")
   
   summary = get_token_collector().get_session_summary()
   print(summary["by_agent"]["researcher"]["output_tokens"])
   print(summary["by_agent"]["writer"]["output_tokens"])

   Agents built with a real LLM instance can also carry a stable agent_id alongside the display name. The collector’s by_agent keying matches whichever attribution the runtime installed (current_agent_name today; scoped team views still filter by Agent.name).

How It Works

Accounting happens inside the native OpenAIClient after every successful completion — one record per tool-loop iteration — and lands in the global TokenCollector.

Session Summary Shape

get_session_summary() returns a plain dict you can read or serialise:

{
    "total_interactions": 1,
    "total_tokens": 320,
    "total_metrics": {
        "input_tokens": 200,
        "output_tokens": 120,
        "cached_tokens": 0,
        "reasoning_tokens": 0,
        "audio_input_tokens": 0,
        "audio_output_tokens": 0,
    },
    "by_model": {
        "gpt-4o-mini": {
            "input_tokens": 200,
            "output_tokens": 120,
            "cached_tokens": 0,
            "reasoning_tokens": 0,
            "audio_input_tokens": 0,
            "audio_output_tokens": 0,
        }
    },
    "by_agent": {
        "researcher": {
            "input_tokens": 200,
            "output_tokens": 120,
            "cached_tokens": 0,
            "reasoning_tokens": 0,
            "audio_input_tokens": 0,
            "audio_output_tokens": 0,
        }
    },
}

In the example above total_tokens is 320 because it is input_tokens (200) + output_tokens (120) — nothing else. Each metrics block also carries cached_tokens, reasoning_tokens, audio_input_tokens, and audio_output_tokens for visibility, but those are subsets of the input/output counts, so they are not added into the total.

Concrete illustration you can compare against:

from praisonaiagents.telemetry.token_collector import TokenMetrics

m = TokenMetrics(input_tokens=1000, output_tokens=500, cached_tokens=800, reasoning_tokens=400)
assert m.total_tokens == 1500  # input + output only, not 2700

The 1500 is the provider’s own reported total. The cached_tokens (800) sit inside the 1000 input tokens, and the reasoning_tokens (400) sit inside the 500 output tokens — summing all four would report 2700, which is wrong.

Scoping to one team (concurrent instances)

The get_token_collector() singleton is process-wide: every agent in every PraisonAIAgents instance writes into the same collector. Reading it directly gives you a combined total across the whole process.

Since PraisonAI PR #4462 (finalized in PR #4470, which closes issue #4446), PraisonAIAgents exposes instance-scoped views that filter the singleton to the team’s own agents — so two concurrent teams never see each other’s spend.

from praisonaiagents import Agent, PraisonAIAgents

team_a = PraisonAIAgents(agents=[Agent(name="A_researcher"), Agent(name="A_writer")])
team_b = PraisonAIAgents(agents=[Agent(name="B_analyst")])

# Run both teams concurrently (or one after another)
team_a.start()
team_b.start()

# Instance-scoped: only team_a's own agents
print(team_a.get_token_usage_summary())
# {'total_metrics': {...team_a only...}, 'by_agent': {'A_researcher': {...}, 'A_writer': {...}}, ...}

# Instance-scoped: only team_b's own agents
print(team_b.get_token_usage_summary())
# {'total_metrics': {...team_b only...}, 'by_agent': {'B_analyst': {...}}, ...}

# Global process-wide totals (unchanged behavior)
from praisonaiagents.telemetry.token_collector import get_token_collector
print(get_token_collector().get_session_summary())
# {'total_metrics': {...team_a + team_b...}, ...}

The scoped methods:

Common Patterns

from praisonaiagents import Agent
from praisonaiagents.telemetry.token_collector import get_token_collector

collector = get_token_collector()
collector.reset()

agent = Agent(llm="gpt-4o-mini")
agent.start("Draft a product announcement")

summary = collector.get_session_summary()
print(summary["total_metrics"]["input_tokens"], summary["total_metrics"]["output_tokens"])

summary = get_token_collector().get_session_summary()
for name, metrics in summary["by_agent"].items():
    print(name, metrics["output_tokens"])

llm.set_current_agent(agent_name="researcher", agent_id="researcher-01")
print(llm.current_agent_name, llm.current_agent_id)
# researcher researcher-01

Latest Call Only

For CLI or Harbor envelopes that need the most recent completion’s usage — not the session total — read OpenAIClient.last_token_metrics. It exposes the latest completion’s TokenMetrics and is cleared when a response carries no usable usage.

Related