From 8fb4dcb119279410f7a02d043323ed23518269e1 Mon Sep 17 00:00:00 2001 From: yuhengcai1 Date: Mon, 26 Oct 2026 00:00:37 -0700 Subject: [PATCH] docs(sdk): explain the independent error-retry threshold Co-authored-by: openhands --- sdk/guides/agent-stuck-detector.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/sdk/guides/agent-stuck-detector.mdx b/sdk/guides/agent-stuck-detector.mdx index 06846dc28..67437ba56 100644 --- a/sdk/guides/agent-stuck-detector.mdx +++ b/sdk/guides/agent-stuck-detector.mdx @@ -9,7 +9,7 @@ import RunExampleCode from "/sdk/shared-snippets/how-to-run-example.mdx"; 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) +2. **Repeating Action-Error Cycles**: The same action repeatedly results in errors. By default, the conversation sends a corrective nudge after 3 failures and stops if the next identical call also fails. 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 @@ -35,6 +35,9 @@ stuck status at any point using `conversation.stuck_detector.is_stuck()`. ## Pattern Detection +The `action_error` threshold controls the corrective nudge for repeated tool errors; one additional failed call triggers the hard stop. The `action_observation` threshold applies to regular tool observations and does not shorten this error-recovery window. Other enabled stuck patterns can still stop the run independently. + + 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