Multi-agent systems loop indefinitely, burning tokens before anyone notices. agent-watchdog intervenes at runtime — the same way a circuit breaker works in distributed systems.
Existing observability tools show you what happened after the fact. By then, you've already burned tokens and hit your budget ceiling.
Two agents debate the same point in different words, indefinitely, with no exit condition.
An uncapped loop burns through your entire API budget before anyone notices the graph is stuck.
Agents wait on each other's output and never produce a result. The graph stalls silently.
LangSmith and AgentOps are powerful, but they tell you what went wrong — not in time to stop it.
agent-watchdog runs inside your LangGraph conditional edges — no external calls, no latency budget, no data leaving your environment.
Collects the last N×2 messages from the graph state on every cycle. Window size is configurable.
Computes average pairwise word-set overlap between the recent window and the previous window. Catches semantic repetition even when exact wording differs.
If the similarity score exceeds your configured threshold (default 55%), the watchdog signals loop_detected. If the cycle count exceeds your limit, it signals limit_reached.
The router returns END before the next agent fires. Zero additional tokens consumed. An intervention report is generated for your logging pipeline.
Detects argumentative cycles using Jaccard word-set similarity across sliding message windows.
Hard cap on graph cycles. If the graph exceeds maxIterations, the watchdog halts regardless of similarity.
Tune similarity threshold, window size, and iteration cap independently per graph or per edge.
Wire onIntervene to your own logger, alerting system, or monitoring pipeline. Fully optional.
Human-readable diagnosis on every intervention: trigger, iteration count, similarity score, last exchanges, and recommended action.
All detection runs in-process. No data leaves your environment, no API keys required for watchdog itself.
Add agent-watchdog to your project. Requires @langchain/langgraph as a peer dependency.
npm install agent-watchdog
Create a watchdog instance with your thresholds. All parameters are optional — defaults work out of the box.
import { AgentWatchdog, createWatchdogRouter } from "agent-watchdog"; import { END } from "@langchain/langgraph"; const watchdog = new AgentWatchdog({ maxIterations: 10, similarityThreshold: 0.55, windowSize: 4, });
Replace any conditional edge with the watchdog router. It halts to END automatically on detection.
const router = createWatchdogRouter(watchdog, "agent_a", (report) => { myLogger.warn(report); }); graph.addConditionalEdges("agent_b", router, { agent_a: "agent_a", [END]: END, });
When agent-watchdog detects a loop, it halts the graph and surfaces a structured report — no guesswork, no post-hoc analysis.
============================================================ AGENT WATCHDOG — INTERVENTION REPORT ============================================================ Trigger : loop_detected Iterations : 8 Similarity : 71% (threshold: 55%) Messages : 9 Last exchange: [Optimist] While AI accelerates scientific discovery, we must ensure equit... [Pessimist] The acceleration you describe comes at the cost of concentrating... [Optimist] Equitable access is precisely why open-source AI development mat... [Pessimist] Open-source development doesn't solve the compute access problem... Diagnosis : agents are recycling the same arguments. Action : graph halted. No further tokens consumed. ============================================================
Detect mutual wait patterns where agents block on each other and no output is produced.
Early-warning callbacks when cumulative token usage approaches configurable budget limits.
Swap in embeddings or TF-IDF for richer semantic loop detection beyond word-set Jaccard.
Bring agent-watchdog's protection to other multi-agent frameworks beyond LangGraph.
The core loop detection library is and always will be open source. Pro tiers add managed monitoring, alerting, and team dashboards.
Open source. Self-hosted. Forever.
For solo developers running agents in production.
For small teams shipping multi-agent products.
For production teams with reliability SLAs.
SSO, on-prem deployment, and custom integrations.
Drop agent-watchdog into any LangGraph graph in under 5 minutes.