From f5ac3e315ab7010c8bc7203cb3b9fb9b506297e1 Mon Sep 17 00:00:00 2001 From: muonchaser <1507272310@qq.com> Date: Mon, 26 Oct 2026 17:58:49 +0800 Subject: [PATCH] docs(sdk): explain remote stuck detection thresholds Co-authored-by: openhands --- sdk/guides/agent-stuck-detector.mdx | 39 +++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/sdk/guides/agent-stuck-detector.mdx b/sdk/guides/agent-stuck-detector.mdx index 06846dc28..ef4b20c41 100644 --- a/sdk/guides/agent-stuck-detector.mdx +++ b/sdk/guides/agent-stuck-detector.mdx @@ -33,6 +33,45 @@ command 5 times in a row. The stuck detector analyzes the event history and iden 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()`. +## Configure thresholds for remote conversations + +Pass `stuck_detection_thresholds` when creating a Python `Conversation`, including +when using a `RemoteWorkspace`: + +```python +conversation = Conversation( + agent=agent, + workspace=remote_workspace, + stuck_detection_thresholds={ + "action_observation": 6, + "alternating_pattern": 8, + }, +) +``` + +The Agent Server accepts the same `stuck_detection_thresholds` object in +`POST /api/conversations`. Each value must be a positive integer. Omitted fields +use the Python defaults: `action_observation=4`, `action_error=3`, `monologue=3`, +and `alternating_pattern=6`. Omitting the object uses all defaults; +`stuck_detection=False` disables detection even when thresholds are supplied. + +The server stores this configuration in conversation metadata and restores it +when reloading or forking the conversation. Thresholds are configured at creation; +there is no endpoint to update them on an existing conversation. + +For the TypeScript remote client, use camelCase options: + +```typescript +const conversation = await manager.createConversation(agent, { + stuckDetectionThresholds: { actionObservation: 6, alternatingPattern: 8 }, +}); +``` + +The client maps these keys to the server's snake_case fields. This requires an +Agent Server version containing the remote-threshold propagation fix; older +servers silently discard the field. This configuration does not change detector +matching rules or the bounded history scan. + ## Pattern Detection The stuck detector compares events based on their semantic content rather than object identity. For example: