⚡ What is LongGuard?

When autonomous LLM agents (LangGraph, LangChain, or custom loops) hit an unexpected hurdle, they often get stuck in repetitive reasoning loops:

• Calling the exact same tool with the exact same parameters over and over.
• Spinning between two reasoning thoughts (semantic oscillation).
• Aimlessly wandering with zero progress while burning thousands of tokens.

Frameworks like LangGraph have a built-in recursion_limit, but it is a hard crash (GraphRecursionError) that drops state, fails the user request, and provides zero opportunity for recovery.

LongGuard is an intelligent circuit breaker middleware. It monitors your agent's chain-of-thought in real time, catches loops early, injects a "Reflect & Pivot" prompt to guide the agent back on track, and only terminates gracefully if recovery fails.

                  ┌─────────────────────────────────┐
                  │      Agent Execution Loop       │
                  └────────────────┬────────────────┘
                                   │  Step N
                                   ▼
                        ┌─────────────────────┐
                        │   LongGuard Hook    │
                        └──────────┬──────────┘
                                   │
               ┌───────────────────┴───────────────────┐
               ▼                                       ▼
     [ No Loop Detected ]                     [ Loop Detected! ]
               │                                       │
        State: CLOSED                                  ▼
      (Normal execution)                      State: REFLECTING
                                                       │
                                            Inject "Reflect & Pivot"
                                            Prompt into Context
                                                       │
                                         ┌─────────────┴─────────────┐
                                         ▼                           ▼
                                    [ Recovers ]              [ Still Stuck ]
                                         │                           │
                                   State: CLOSED               State: OPEN
                                   (Runs to end)            (Graceful Termination)

🚀 Quick Start

1. Installation

# Core package (zero heavy dependencies)
pip install longguard

# With LangGraph integration
pip install longguard[langgraph]

# With LangChain integration
pip install longguard[langchain]

2. LangGraph Integration (1 Line)

Compatible with LangGraph 1.0+ and modern multimodal models (Claude, Gemini, OpenAI):

from langgraph.graph import StateGraph
from longguard.integrations.langgraph import add_guard_to_graph
from longguard import GuardConfig

# 1. Define your standard LangGraph workflow
workflow = StateGraph(AgentState)
workflow.add_node("agent", agent_node)
workflow.add_node("tools", tool_node)
workflow.add_edge("agent", "tools")
workflow.add_conditional_edges("tools", should_continue)

# 2. Wrap with LongGuard — that's it!
workflow = add_guard_to_graph(workflow, GuardConfig())
app = workflow.compile()

# 3. Access execution analytics after the run
guard = workflow.__longguard__
print(guard.get_report().summary())

3. Standalone / Custom Agent Loop

If you run a custom while loop or proprietary agent orchestrator:

from longguard import CircuitBreaker, GuardConfig, AgentStep

breaker = CircuitBreaker(GuardConfig(
    tool_repeat_threshold=3,    # 3 identical tool calls = trigger
    max_tokens_per_run=50_000,  # Hard token cap
))

for step in run_agent():
    decision = breaker.check(AgentStep(
        step_number=step.index,
        thought=step.thought,
        action=step.tool_name,
        action_input=step.arguments,
        observation=step.tool_output,
        tokens_used=step.tokens,
    ))

    if decision.action == "reflect":
        # Inject the recovery advice into your agent's message list
        messages.append({"role": "user", "content": decision.inject_prompt})
    elif decision.action == "kill":
        print(f"Halted safely: {decision.reason}")
        break

# View summary report
print(breaker.report.summary())

🔍 The 4 Loop Detectors

LongGuard runs four lightweight detectors concurrently at every step:

🔄 The Circuit Breaker State Machine

LongGuard adapts standard distributed systems circuit breaker patterns to LLM cognition:

1. CLOSED (Normal): All checks pass. The agent runs freely.
2. REFLECTING (Intervention): A loop was detected. LongGuard injects an automated Reflect & Pivot prompt instructing the agent:

   "You have called {tool} {count} times with the same arguments. Stop. Try a different tool or synthesize your current findings."

3. HALF-OPEN (Observation): The agent gets one chance to demonstrate progress following reflection.
4. OPEN (Graceful Termination): If the loop persists after reflection, LongGuard terminates execution cleanly, preserving full trace telemetry and token usage.

📊 LongGuard vs. LangGraph recursion_limit

⚙️ Configuration at a Glance

All behavior can be customized via GuardConfig:

from longguard import GuardConfig

config = GuardConfig(
    # Loop Detection Sensitivity
    tool_repeat_threshold=3,          # Number of repeated tool calls before reflection
    tool_repeat_window=6,             # History window to examine
    dead_end_threshold=5,             # Steps with no progress before triggering
    token_velocity_multiplier=3.0,    # Spike multiplier vs rolling baseline

    # Hard Safety Guardrails
    max_tokens_per_run=50_000,        # Hard stop if agent burns > 50k tokens
    max_steps=30,                     # Maximum steps permitted
    max_reflections=2,                # Maximum recovery attempts before kill
)

👉 For detailed documentation on custom detectors, embedding backends, and LangSmith telemetry, see the Full Documentation.

🌐 Part of the EnDevSols AI Infrastructure Suite

LongGuard works alongside our other open-source tools to secure production LLM pipelines:

• LongParser — Fast, privacy-first local document parser (PDF, DOCX, XLSX).
• LongProbe — Sub-second RAG retrieval regression testing with pytest.
• LongTracer — Post-generation hallucination detection & claim verification.
• LongGuard — In-flight runtime cognitive circuit breaker & loop recovery.

🤝 Contributing & Community

We love contributions!

• Submit bug reports and feature ideas via GitHub Issues.
• See CONTRIBUTING.md for development environment setup and testing guidelines.

📄 License

LongGuard is open-source software released under the MIT License.