Cost Tracking

Cost Tracking

pydantic-deep tracks token usage and USD costs automatically using CostTrackingMiddleware from pydantic-ai-middleware. Cost tracking is enabled by default.

!!! tip "Requires middleware" Cost tracking uses pydantic-ai-middleware with genai-prices for pricing data. Install with: bash pip install pydantic-deep[middleware]

Quick Start

from pydantic_deep import create_deep_agent

# Cost tracking is ON by default
agent = create_deep_agent()

# Disable cost tracking
agent = create_deep_agent(cost_tracking=False)

Budget Limits

Set a maximum cumulative cost. When exceeded, the next run raises BudgetExceededError:

agent = create_deep_agent(
    cost_budget_usd=5.00,  # $5 budget
)

Cost Update Callback

Monitor costs in real-time:

from pydantic_ai_middleware import CostInfo

def on_cost(info: CostInfo):
    print(f"Run cost: ${info.run_cost_usd:.4f}")
    print(f"Total: ${info.cumulative_cost_usd:.4f}")
    print(f"Tokens: {info.run_input_tokens} in / {info.run_output_tokens} out")

agent = create_deep_agent(
   
    cost_budget_usd=10.00,
)

Configuration

CostInfo Fields

The CostInfo dataclass provides both per-run and cumulative metrics:

How It Works

1. CostTrackingMiddleware wraps the agent via MiddlewareAgent
2. After each run, it reads result.usage() for token counts
3. Token costs are calculated using genai-prices (model-specific pricing)
4. CostInfo is passed to the on_cost_update callback
5. If cumulative_cost_usd exceeds cost_budget_usd, subsequent runs raise BudgetExceededError

Next Steps

• Middleware — Middleware system and permissions
• Context Manager — Token tracking and auto-compression
• Agents — Full agent configuration