Skip to main content
A ready-to-run example is available here!
The Stuck Detector automatically identifies when an agent enters unproductive patterns such as repeating the same actions, encountering repeated errors, or engaging in monologues. By analyzing the conversation history after the last user message, it detects five types of stuck patterns:
  1. Repeating Action-Observation Cycles: The same action produces the same observation repeatedly (4+ times)
  2. Repeating Action-Error Cycles: The same action repeatedly results in errors (3+ times)
  3. Agent Monologue: The agent sends multiple consecutive messages without user input or meaningful progress (3+ messages)
  4. Alternating Patterns: Two different action-observation pairs alternate in a ping-pong pattern (6+ cycles)
  5. Context Window Errors: Repeated context window errors that indicate memory management issues
When enabled (which is the default), the stuck detector monitors the conversation in real-time and can automatically halt execution when stuck patterns are detected, preventing infinite loops and wasted resources.
For more information about the detection algorithms and how pattern matching works, refer to the StuckDetector source code.

​
How It Works

In the ready-to-run example, the agent is deliberately given a task designed to trigger stuck detection - executing the same ls command 5 times in a row. The stuck detector analyzes the event history and identifies the repetitive pattern:
  1. The conversation proceeds normally until the agent starts repeating actions
  2. After detecting the pattern (4 identical action-observation pairs), the stuck detector flags the conversation as stuck
  3. The conversation can then handle this gracefully, either by stopping execution or taking corrective action
The example demonstrates that stuck detection is enabled by default (stuck_detection=True), and you can check the stuck status at any point using conversation.stuck_detector.is_stuck().

​
Pattern Detection

The stuck detector compares events based on their semantic content rather than object identity. For example:
  • Actions are compared by their tool name, action content, and thought (ignoring IDs and metrics)
  • Observations are compared by their observation content and tool name
  • Errors are compared by their error messages
  • Messages are compared by their content and source
This allows the detector to identify truly repetitive behavior while ignoring superficial differences like timestamps or event IDs.

​
Ready-to-run Example

This example is available on GitHub: examples/01_standalone_sdk/20_stuck_detector.py
examples/01_standalone_sdk/20_stuck_detector.py
import os

from pydantic import SecretStr

from openhands.sdk import (
    LLM,
    Conversation,
    Event,
    LLMConvertibleEvent,
    get_logger,
)
from openhands.tools.preset.default import get_default_agent


logger = get_logger(__name__)

# Configure LLM
api_key = os.getenv("LLM_API_KEY")
assert api_key is not None, "LLM_API_KEY environment variable is not set."
model = os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929")
base_url = os.getenv("LLM_BASE_URL")
llm = LLM(
    usage_id="agent",
    model=model,
    base_url=base_url,
    api_key=SecretStr(api_key),
)

agent = get_default_agent(llm=llm)

llm_messages = []


def conversation_callback(event: Event):
    if isinstance(event, LLMConvertibleEvent):
        llm_messages.append(event.to_llm_message())


# Create conversation with built-in stuck detection
conversation = Conversation(
    agent=agent,
    callbacks=[conversation_callback],
    workspace=os.getcwd(),
    # This is by default True, shown here for clarity of the example
    stuck_detection=True,
)

# Send a task that will be caught by stuck detection
conversation.send_message(
    "Please execute 'ls' command 5 times, each in its own "
    "action without any thought and then exit at the 6th step."
)

# Run the conversation - stuck detection happens automatically
conversation.run()

assert conversation.stuck_detector is not None
final_stuck_check = conversation.stuck_detector.is_stuck()
print(f"Final stuck status: {final_stuck_check}")

print("=" * 100)
print("Conversation finished. Got the following LLM messages:")
for i, message in enumerate(llm_messages):
    print(f"Message {i}: {str(message)[:200]}")

# Report cost
cost = llm.metrics.accumulated_cost
print(f"EXAMPLE_COST: {cost}")
You can run the example code as-is.
The model name should follow the LiteLLM convention: provider/model_name (e.g., anthropic/claude-sonnet-4-5-20250929, openai/gpt-4o). The LLM_API_KEY should be the API key for your chosen provider.
ChatGPT Plus/Pro subscribers: You can use LLM.subscription_login() to authenticate with your ChatGPT account and access Codex models without consuming API credits. See the LLM Subscriptions guide for details.

​
Next Steps