costs_by_agent
Break down token costs by agent, showing total spend, request count, average cost per request, primary provider and model, and share of total spend, sorted by cost descending.
Instructions
Per-agent cost breakdown — total spend + request count + avg cost-per-request + primary provider/model + share of total spend, sorted by cost descending.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| window_hours | No |
Implementation Reference
- The call_tool handler for 'costs_by_agent': fetches entries in the window, aggregates via _by_agent(), wraps in AgentCostBreakdown, and serializes.
if name == "costs_by_agent": from openclaw_cost_tracker_mcp.analysis import _by_agent window_hours = max(1, min(int(arguments.get("window_hours", 168)), 720)) entries = await _entries_in_window(window_hours) agents = _by_agent(entries) return _serialize( AgentCostBreakdown( window_hours=window_hours, total_cost_usd=sum(e.cost_usd for e in entries), agents=agents, ) ) - AgentCostBreakdown model — the response schema for the costs_by_agent tool.
class AgentCostBreakdown(BaseModel): """Response for `costs_by_agent`.""" window_hours: int total_cost_usd: float agents: list[AgentCost] - AgentCost model — per-agent cost roll-up with total spend, request count, total tokens, avg cost/request, primary provider/model, and share of total.
class AgentCost(BaseModel): """Cost roll-up for a single agent/channel/skill over a window.""" model_config = ConfigDict(frozen=True) agent_id: str total_cost_usd: float request_count: int total_tokens: int avg_cost_per_request_usd: float primary_provider: Provider | None = None primary_model: str | None = None share_of_total_pct: float - _by_agent() — the pure aggregation function that groups CostEntry records by agent_id, computes total cost, request count, tokens, avg cost/request, primary provider/model, and share of total, sorted by cost descending.
def _by_agent(entries: list[CostEntry], top_n: int | None = None) -> list[AgentCost]: if not entries: return [] total = sum(e.cost_usd for e in entries) or 1.0 grouped: dict[str, list[CostEntry]] = defaultdict(list) for e in entries: agent = e.agent_id or "<unattributed>" grouped[agent].append(e) out: list[AgentCost] = [] for agent, group in grouped.items(): cost = sum(e.cost_usd for e in group) # Most-common provider/model in the group provider_counts = Counter(e.provider for e in group) model_counts = Counter((e.provider, e.model) for e in group) primary_provider = provider_counts.most_common(1)[0][0] if provider_counts else None primary_model = model_counts.most_common(1)[0][0][1] if model_counts else None out.append( AgentCost( agent_id=agent, total_cost_usd=cost, request_count=len(group), total_tokens=sum(e.total_tokens for e in group), avg_cost_per_request_usd=cost / len(group), primary_provider=primary_provider, primary_model=primary_model, share_of_total_pct=100.0 * cost / total, ) ) out.sort(key=lambda a: a.total_cost_usd, reverse=True) if top_n is not None: out = out[:top_n] return out - src/openclaw_cost_tracker_mcp/server.py:79-91 (registration)Tool registration: defines the 'costs_by_agent' tool with name, description, and inputSchema (window_hours integer).
Tool( name="costs_by_agent", description=( "Per-agent cost breakdown — total spend + request count + avg cost-per-request " "+ primary provider/model + share of total spend, sorted by cost descending." ), inputSchema={ "type": "object", "properties": { "window_hours": {"type": "integer", "default": 168}, }, "required": [], },