01
tool_loop
V0
Same tool, ≥3 cosine-similar calls in 60s
Agent stuck on a tool it's not getting unstuck from
Open source·SDK 1.0.2·Apache-2.0
Mid-run token waste detection for AI agents.
A Python SDK that wraps your LLM client and runs 15 deterministic rules while the session is still running— loops, context bloat, retries, and more. log, alert, or block. In-process, sub-ms overhead, no signup required.
rules
15
providers
9
overhead
<1ms
modes
log · alert · block
license
Apache-2.0
[01] why token-sentinel
What you get in the library.
A thin SDK, not a platform pitch. Install it, wrap the client, handle events in your code.
benefits
Mid-run waste and quality signals for agent workloads — so you can react before the invoice, without replacing your observability stack.
In-process detection
Sits on the LLM client. No extra network hop for the rule engine. Works offline in log mode.
Mid-run, not next month
Catch tool loops, retry storms, context bloat, and quality thrash while the agent is still calling.
log · alert · block
Start safe in log mode. Escalate when you trust the signal. Same callback contract in every mode.
15 rules by default
Agent, vision, audio, voice, rerank, and repair patterns — deterministic, configurable thresholds.
9 native providers
Anthropic, OpenAI (incl. Whisper), Gemini, Bedrock, Cohere, Voyage, Deepgram, ElevenLabs, Replicate — plus OpenAI-compatible gateways.
Plays with your stack
Use alongside Langfuse, LangSmith, or Datadog. We instrument the client layer; they can still own traces.
[02] quickstart · ~5 min
Install, wrap, handle.
No account. No telemetry unless you opt into Cloud later. Most teams stay in log mode first.
step 01
Install
Core has zero required deps. Add a provider extra as needed.
$pip install token-sentinel[anthropic]
Or: [openai], [gemini], [bedrock], [all]
step 02
Wrap the client
Same shape across providers. Streaming and async preserved.
agent.py
pythonfrom token_sentinel import Sentinel
import anthropic
sentinel = Sentinel(project="my-agent", mode="log") # log | alert | block
client = sentinel.wrap(anthropic.Anthropic())step 03
Handle events
Typed callback when a rule fires. Log, notify, or raise BudgetExceeded.
agent.py
python@sentinel.on_leak
def handle(event):
print(f"WASTE [{event.type}] burn=${event.estimated_burn:.4f}")[03] rules · SDK 1.0.2
15 waste & quality classes, on by default.
Deterministic rules for agent loops, context bloat, tool thrash, vision/audio waste, and conversational repair.
id
rule
signal
fires when
02
context_bloat
V0
Prompt-tokens-per-turn slope > 1500/turn
ReAct context window growing without bound
03
embedding_waste
V0
Exact-hash repeat embedding within session
Same vector look-up paid for repeatedly
04
zombie
V0
No user-facing output for 5 min, calls firing
Background agent that nobody is reading
05
model_misroute
V0
Classification prompt sent to a frontier model
Opus answering a yes/no — Haiku would suffice
06
retry_storm
V0
≥5 identical calls in 30s
Provider 529 + no exponential backoff
07
tool_definition_bloat
V0
≥30 tool defs OR ≥30KB of tool JSON
The MCP problem — 55K tokens before user types
08
retrieval_thrash
V0
≥3 retrieval calls with overlapping queries in 120s
RAG pipeline that keeps re-fetching
09
vision_re_upload
Vision
Same image SHA-256 (or phash distance ≤6) across calls
Same screenshot re-uploaded turn after turn
10
vision_high_detail_misroute
Vision
High-detail flag on low-detail-suitable image
Paying 4× for detail you don't need
11
vision_cost_concentration
Vision
Vision dollars concentrated in <5% of sessions
One agent eating the vision budget
12
audio_multichannel_doubling
Audio
Deepgram channels≥2 with multichannel=true
Per-channel billing doubled without reason
13
voice_switching_loop
Voice
Same text_hash across ≥3 ElevenLabs voice_ids in 10s
A/B test scaffold leaked into production
14
rerank_thrash
Rerank
Same Cohere rerank request_hash across ≥2 calls in 30s
Reranks fired without a cache layer
15
repair_loop
Repair
≥2 correction-shaped user turns + similar regenerations within 10 turns
Cost-aligned proxy for hallucination/grounding failures
[04] modes
Three modes. One callback.
Escalate log → alert → block when you trust the rules for your workloads.
01 · default start
mode="log"
Events go to your handler only. Use this until the signal matches real traffic.
02 · optional cloud
mode="alert"
Forward events to Cloud / webhooks when you connect a project. Still non-blocking.
03 · when ready
mode="block"
Raises BudgetExceeded at the next call boundary so your agent can stop cleanly.
[05] cloud
Optional hosted Cloud (waitlist).
The SDK is complete without Cloud. Hosted dashboards and fleet controls are early-access for design partners.
not required for the SDK
If you want budgets, a savings view, and an operator kill-switch later, join the waitlist. Until then, pip install token-sentinel is enough.