Detection runs deterministically over the agent graph, on your machine, in your process.
Two lines wire agentSonar into your existing setup. It instruments delegation calls between agents without touching prompts, API keys, or any LLM call directly. Nothing leaves your machine.
from agentsonar import monitor graph = monitor(your_graph.compile()) # that's it. run your graph as normal.
agentSonar instruments the delegation layer, not LLM calls. Your prompts are untouched.
Everything runs in-process. No data leaves your machine unless you opt into telemetry.
agentSonar observes your agent graph directly. It doesn't need credentials.
Native adapters for LangGraph and CrewAI. Custom Python or Node for everything else.
agentSonar doesn't watch individual spans — it models the graph of agent-to-agent delegations and spots pathological patterns that look perfectly healthy span by span.
// builds a directed graph of delegation events researcher → writer // edge weight: 1 writer → reviewer // edge weight: 1 reviewer → researcher // edge weight: 1 ← closes a cycle // cycle detector fires on rotation 1 // WARNING threshold: 5 rotations (configurable) // CRITICAL threshold: 15 rotations (configurable)
Agents cycling work in a circle. Fires when a directed cycle closes and repeats past threshold.
The same agent called with the same task multiple times. Fires when repetitions exceed threshold.
A burst of agent-to-agent calls wildly outside the session's baseline rate.
Same tool, same args, same result — called repeatedly with nothing new ever coming back.
A tool call starts and never returns. The agent waits indefinitely, blocking the pipeline.
Runaway fan-out spawns far more subagents than expected. Token bill multiplies silently.
Hammers the same failing endpoint repeatedly instead of stopping or routing around it.
Session filling toward the context limit — where quality degrades or the run fails entirely.
Every threshold is overridable. loop_threshold=3 for tighter production guardrails.
The moment a threshold trips, agentSonar writes to three places simultaneously. All of it lands on disk. None of it requires a network connection.
[SONAR 14:32:01] session started (id: 43b4782630244f8d) [SONAR 14:32:03] cycle found: researcher→writer→reviewer [SONAR 14:32:09] ⚠ WARNING cycle · 5 rotations · 3,600 tokens [SONAR 14:32:18] 🚨 CRITICAL cycle · 15 rotations · 11,400 tokens
Alerts fire as the failure forms. Pipe to your logging stack or read live in your terminal.
Every event flushed on write. tail -f timeline.jsonl while agents run.
Written on shutdown. No external CSS, JS, or network. Email it or attach to a ticket.
Consistent IDs per pattern across runs. Correlate today's loop with last Tuesday's.
Detection tells you what happened. Prevent Mode (opt-in) raises a typed
PreventError the moment a failure crosses its trip threshold —
before the next LLM call. Your code catches it, you decide what to do.
from agentsonar import monitor_orchestrator, PreventError sonar = monitor_orchestrator(config={ "prevent": {"cyclic_delegation": True} }) try: while True: sonar.delegation("researcher", "writer") # ... agents run ... except PreventError as e: print(f"Stopped: {e.reason}") print(f"Loop: {' → '.join(e.cycle_path)}")
PreventError carries the cycle path, rotation count, and tokens burned. Catch and log exactly what happened.
One config key opt-in. Detection always runs. Prevent only activates when you ask for it.
LangGraph, Custom Python, Custom Node, OMA sidecar. CrewAI Prevent Mode coming soon.
Enable Prevent for loops only, or enable per-type. Repeated calls and spike auto-stop on the way.
None of these are shipped yet. Called out so you know where the project is headed.
OpenAI Agents SDK, Anthropic Claude Agent SDK, AutoGen. Native adapters, same two-line wire-in.
Per-customer, per-tool dollar attribution. The CFO-facing dashboard that shows what agentSonar saved.
Web UI on top of the JSONL timeline. Real-time view of every agent session.