Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions sdk/guides/agent-stuck-detector.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down