docs(sdk): maxLoopCount default is documented as 25 but the code default is MAX_LOOP_COUNT = 100
Description
The SDK documents maxLoopCount as defaulting to 25, but the agent actually defaults to 100. The three stale statements are:
packages/ui-tars/sdk/README.md:181—- `maxLoopCount`: Maximum number of interaction loops (default: 25)docs/sdk.md:181— the same line (the two files are byte-identical; both are blobe3c44d6onmain)packages/ui-tars/sdk/src/types.ts:104—/** Maximum number of turns for Agent to execute, @default 25 */
The real default comes from MAX_LOOP_COUNT, which is 100:
// packages/ui-tars/shared/src/constants/vlm.ts:6
export const MAX_LOOP_COUNT = 100;// packages/ui-tars/sdk/src/GUIAgent.ts:72-78
const {
signal,
onData,
onError,
retry = {},
maxLoopCount = MAX_LOOP_COUNT,
} = this.config;and it is enforced at packages/ui-tars/sdk/src/GUIAgent.ts:162 (if (loopCnt >= maxLoopCount)).
25 is the minimum, not the default
The number 25 is the lower bound of the desktop app's setting, and the repo's own settings page already distinguishes the two:
// apps/ui-tars/src/main/store/validate.ts:28
maxLoopCount: z.number().min(25).max(200).optional(),<!-- docs/setting.md:148-153 -->
| Property | Details |
| ------------ | -------- |
| **Type** | `number` |
| **Required** | `true` |
| **Options** | `[25, 200]` |
| **Default** | `100` |The app's own default agrees with 100:
// apps/ui-tars/src/main/store/setting.ts:27
maxLoopCount: 100,So docs/setting.md says the default is 100 while docs/sdk.md / packages/ui-tars/sdk/README.md / the GUIAgentConfig JSDoc say 25, for what is meant to be the same limit. git log -S"MAX_LOOP_COUNT = 25" -- packages/ui-tars returns nothing, i.e. the constant has never been 25, so the documentation is the stale side rather than the code.
Actual Impact
An SDK integrator who reads default: 25 and sizes around it — a watchdog/timeout budget, a per-run cost cap, or an "the agent will give up after ~25 loops" assumption — gets up to 100 model calls before GUIAgent reports ErrorStatusEnum.REACH_MAXLOOP_ERROR (packages/ui-tars/sdk/src/GUIAgent.ts:162-168), i.e. four times the documented bound. The JSDoc is also what surfaces in editor hover docs, so the wrong number is reproduced in the IDE, not only on the site.
Proposed Fix
Correct the three documented defaults to 100 and leave the behavior alone:
packages/ui-tars/sdk/README.md:181:25→100docs/sdk.md:181:25→100packages/ui-tars/sdk/src/types.ts:104:@default 25→@default 100
Deliberately out of scope:
docs/archive-1.0/sdk.md:182carries the same line but the file opens with> [!WARNING] This document has been archived., so it is a frozen snapshot and should stay as it was.- Changing
MAX_LOOP_COUNTitself would alter runtime behavior for every SDK caller that omits the option, which is not what this report is about.
Happy to open the PR for this myself.
Source: bytedance/UI-TARS-desktop