This is a submission for the Hermes Agent Challenge.
I ran a Hermes research agent across 50 literature review tasks and forgot to check the bill until the next morning. Three dollars gone. The agent had retried a bunch of failed web searches and each retry cost money.
The fix is obvious in hindsight: track cost as you go and stop when you hit the limit. That's agent-cost-guard.
Raise when the limit hits
from agent_cost_guard import CostGuard
guard = CostGuard(limit_usd=1.00)
# Inside your agent loop:
response = client.messages.create(model="claude-sonnet-4-5", ...)
cost = calculate_cost(response.usage)
guard.add(cost, label="research_turn") # raises CostLimitExceeded if over $1
Warn before it hits
def on_warn(w):
log.warning(f"Cost at {w.pct_used:.0%} — ${w.total_usd:.4f} of ${w.limit_usd:.4f}")
guard = CostGuard(
limit_usd=1.00,
warn_at=[0.5, 0.8],
on_warn=on_warn,
)
The callback fires once per threshold and never again unless you call guard.reset().
Track by label
guard.add(0.05, label="web_search")
guard.add(0.12, label="llm_synthesis")
guard.add(0.03, label="web_search")
s = guard.summary()
print(s.by_label)
# {"web_search": 0.08, "llm_synthesis": 0.12}
Now you know where the money went.
Keep going past the limit
guard = CostGuard(limit_usd=0.50, stop_on_limit=False)
guard.add(1.00) # no exception
print(guard.ok) # False
print(guard.remaining_usd) # -0.50
Useful for logging-only mode when you want to measure but not block.
Check manually
guard.check() # raises CostLimitExceeded if total > limit
Call it at checkpoints rather than after every single add.
Summary report
s = guard.summary()
print(str(s))
# Cost: $0.20 / $1.00 (20.0% used)
# Entries: 3
# Breakdown:
# llm_synthesis: $0.12
# web_search: $0.08
Factory with sensible defaults
from agent_cost_guard import make_cost_guard
guard = make_cost_guard(limit_usd=1.00, on_warn=on_warn)
# warn_at defaults to [0.5, 0.8]
Zero dependencies
Standard library only: dataclasses, time. Nothing else.
pip install agent-cost-guard