LongGuard

In-Flight Circuit Breaker & Reasoning Loop Recovery

When autonomous LLM agents hit an unexpected hurdle, they often get trapped repeating the exact same tool call, oscillating between two thoughts, or burning thousands of tokens in a dead-end loop. LongGuard monitors your agent in real time, injects a Reflect & Pivot prompt to recover gracefully, and enforces hard token and USD cost guardrails.

$pip install longguard
View on GitHubDocumentation Build With Us

Stop runaway agent loops before they burn your budget

Real-time loop detection, intelligent prompt recovery, and hard dollar-cost caps for production AI agents.

4 Real-Time Loop Detectors

Catches Tool Repeat, Semantic Oscillation, Dead-End Drift, and Token Velocity spikes with sub-millisecond evaluation overhead.

Reflect & Pivot Injection

Injects targeted recovery prompts when an agent gets stuck, guiding it to change strategy before resorting to a graceful halt.

1-Line Framework Wrappers

Drop-in support for LangGraph 1.0+ (`add_guard_to_graph`), LangChain (`GuardedAgentExecutor`), CrewAI (`add_guard_to_crew`), and `@guarded`.

Safe LangGraph Resume

Continue eligible stopped runs via `compile_guarded_graph` and `GuardedGraph.resume()` without replaying completed tool calls.

Dollar Cost & Token Caps

Built-in model pricing registry. Set `max_cost_usd` and `max_tokens_per_run` to hard-stop runaway agents before they burn your budget.

Full Run Telemetry

Detailed `GuardReport` with per-step token, cost, and detector analytics. Export to JSON/YAML and keep tool-call histories protocol-clean.

Detectors & Integrations

4 Loop Detectors

  • Tool Repeat (identical tool + args)
  • Semantic Oscillation (A ↔ B cycling)
  • Dead-End Drift (zero new info)
  • Token Velocity (exponential spikes)

Frameworks & SDKs

  • LangGraph 1.0+ (graph & checkpoint)
  • LangChain 1.0+ & CrewAI
  • Raw OpenAI & Anthropic SDKs
  • Universal @guarded decorator

Safety & Observability

  • Reflect & Pivot prompt injection
  • Safe checkpoint resume (no replay)
  • Real-time USD budget enforcement
  • JSON/YAML GuardReport telemetry
Part of the Long Suite

LongGuard is the runtime safety layer of the complete RAG & Agent ecosystem

The Long Suite covers the full production AI lifecycle. LongParser prepares your documents. LongTrainer builds the chatbot. LongTracer verifies the answers. LongProbe tests the retrieval. LongGuard protects runtime agent loops. LongCache eliminates repetitive token costs.

Parse
LongParser
Build
LongTrainer
Verify
LongTracer
Test
LongProbe
Guard
LongGuard
Cache
LongCache
View the Long Suite ecosystem

Common questions

LangGraph's built-in `recursion_limit` is a blind step counter that triggers a hard crash (`GraphRecursionError`), dropping conversation state and offering zero opportunity for recovery. LongGuard inspects your agent's reasoning in real time across 4 specialized detectors, catches loops early (often in 3–4 steps instead of 25), injects a 'Reflect & Pivot' recovery prompt to steer the agent back on track, and only halts gracefully while preserving complete state and token analytics.
LongGuard monitors every in-flight step with four detectors: (1) Tool Repeat — catches calling the same tool with identical inputs N times in a row; (2) Semantic Oscillation — catches cycling between the same conflicting reasoning concepts (e.g., Option A → Option B → Option A); (3) Dead-End Drift — catches 5+ steps that yield zero new observations or repetitive error strings; and (4) Token Velocity — catches sudden exponential token spikes per step, such as dumping giant raw HTML payloads into context.
When a detector trips for the first time, LongGuard doesn't immediately kill the run. Instead, it returns a `reflect` decision and injects a contextual system/user prompt explaining what loop the agent fell into (e.g., repeating `search('revenue 2025')`) and instructing it to try an alternative tool, broaden parameters, or synthesize from existing context. If recovery succeeds, the run finishes normally; if the agent continues looping past `max_reflections`, LongGuard gracefully halts (`kill`).
Using `compile_guarded_graph(workflow, GuardConfig(), checkpointer=checkpointer)`, LongGuard wraps your LangGraph workflow at node boundaries. If a run is halted, you can inspect the checkpoint and explicitly call `guarded_graph.resume(thread_id)` to continue from the exact stopped state without replaying completed tool calls—preserving tool-call IDs, conversation protocol consistency, and per-run token reports.
Yes. LongGuard's core `CircuitBreaker` has zero framework dependencies. You can use the universal `@guarded` decorator on any Python function, generator, or async loop, or use `AgentStep.from_openai_response()` and `AgentStep.from_anthropic_response()` directly inside a raw `openai` or `anthropic` SDK `while` loop. It also includes 1-line integration for CrewAI (`add_guard_to_crew`).
LongGuard ships with a built-in model pricing registry (`list_supported_models()`) covering GPT-4o, Claude 3.5/3.7, Gemini 2.5, and more. Pass `model='gpt-4o'` and `max_cost_usd=0.50` in `GuardConfig`, and LongGuard calculates real-time USD cost per step from token usage, halting the agent gracefully the moment a run exceeds your dollar budget.

Need production AI agents with built-in runtime guardrails?

We build reliable LangGraph and multi-agent systems using the full Long Suite stack. Book a free discovery call to discuss your requirements.

Book a Discovery Call View All Open Source Tools