# UI-TARS Loop Interval Parameter: Configuration and Optimization Guide

> Optimize your UI-TARS agent with the loopIntervalInMs parameter. Learn how to configure this crucial setting to balance automation speed and system stability for peak performance.

- Repository: [Bytedance Inc./UI-TARS-desktop](https://github.com/bytedance/UI-TARS-desktop)
- Tags: how-to-guide
- Published: 2026-05-10

---

**The `loopIntervalInMs` parameter is a configurable delay in milliseconds that controls the pause duration between successive iterations of the UI-TARS agent's main execution loop, balancing automation speed against system stability.**

The UI-TARS-desktop repository by ByteDance provides a comprehensive SDK for building GUI automation agents. Understanding how to configure the **loop interval parameter** is critical for optimizing agent performance across different hardware capabilities and application responsiveness requirements.

## What Is the Loop Interval Parameter?

The loop interval parameter, represented as `loopIntervalInMs` in the SDK configuration, defines the mandatory sleep duration the agent inserts between consecutive execution cycles. This parameter prevents the agent from overwhelming the system with rapid-fire actions.

### Type Definitions and Defaults

In [`packages/ui-tars/sdk/src/types.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/types.ts), the configuration interface declares this field with a default value of `0` milliseconds. According to the source comments, this represents "Time interval between two loop iterations (in milliseconds)", where `0` instructs the agent to run iterations as fast as possible without artificial delays.

### Runtime Implementation

The actual throttling logic resides in [`packages/ui-tars/sdk/src/GUIAgent.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/GUIAgent.ts). Before processing each new iteration, the agent checks the configured value:

```typescript
// packages/ui-tars/sdk/src/GUIAgent.ts (lines 24-32)
if (this.config.loopIntervalInMs && this.config.loopIntervalInMs > 0) {
  logger.info(`[GUIAgent] sleep for ${this.config.loopIntervalInMs}ms before next loop`);
  await sleep(this.config.loopIntervalInMs);
}

```

When `loopIntervalInMs` is omitted or set to `0`, the sleep call is bypassed, allowing immediate iteration.

## When to Adjust the Loop Interval Parameter

Adjusting this value depends on your specific environment constraints, target application behavior, and performance requirements.

### Increase for Heavy UI Workloads

When automating applications with complex animations, frequent DOM updates, or heavy rendering pipelines, increase the interval to prevent **race conditions** and **missed clicks**. The default desktop application setting in [`apps/ui-tars/src/main/store/setting.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/apps/ui-tars/src/main/store/setting.ts) uses `1000` milliseconds specifically to accommodate standard UI rendering delays and ensure actions complete before the next iteration begins.

### Optimize for Resource Constraints

On low-end CPUs or resource-constrained environments, setting a positive interval (e.g., `500` to `1000` ms) reduces CPU usage by preventing tight busy-loops that consume excessive processing power. This throttling allows the system to handle other processes between automation steps.

### Decrease for Latency-Critical Automation

For lightweight UIs or scenarios where minimal response time is critical, maintain the value at `0` or use small increments (e.g., `100` ms). This configuration eliminates artificial delays between actions, maximizing throughput when the underlying system can handle rapid state changes.

### Debugging and External Synchronization

During testing or when integrating with external screenshot APIs, larger intervals make logs easier to follow and provide time for remote services to process requests. This is particularly valuable when the agent must wait for network-dependent UI updates to propagate.

## How to Configure the Loop Interval

### SDK-Level Configuration

When instantiating the GUIAgent directly in your TypeScript implementation:

```typescript
import { GUIAgent } from '@ui-tars/sdk';

const agent = new GUIAgent({
  operator: myOperator,
  model: myModel,
  loopIntervalInMs: 500,  // 500ms pause between loops
  maxLoopCount: 25,
});

```

### Desktop Application Settings

The UI-TARS desktop application persists user preferences and passes them to the SDK via the runAgent service in [`apps/ui-tars/src/main/services/runAgent.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/apps/ui-tars/src/main/services/runAgent.ts):

```typescript
import { SettingStore } from '@main/store/setting';

const settings = SettingStore.getStore();        // Retrieves stored config
const interval = settings.loopIntervalInMs;     // Default: 1000ms

await guiAgent.run({
  // ...other configuration parameters
  loopIntervalInMs: interval,                  // Applied to agent execution
});

```

## Summary

- The **loop interval parameter** (`loopIntervalInMs`) controls the delay between agent execution cycles in the UI-TARS SDK, implemented via `sleep()` calls in [`GUIAgent.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/GUIAgent.ts).
- Default SDK behavior is `0` ms (maximum speed), while the desktop application in [`apps/ui-tars/src/main/store/setting.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/apps/ui-tars/src/main/store/setting.ts) defaults to `1000` ms for end-user stability.
- **Increase** the interval when handling heavy UIs, limited hardware resources, or external API synchronization requirements.
- **Decrease** or set to `0` when latency is critical and the target UI is lightweight.
- Configuration occurs through the `GUIAgentConfig` interface or the desktop application's `SettingStore`.

## Frequently Asked Questions

### What happens if I set loopIntervalInMs to 0?

Setting the value to `0` removes artificial delays, causing the agent to iterate as fast as the CPU allows. According to the implementation in [`packages/ui-tars/sdk/src/GUIAgent.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/GUIAgent.ts), the sleep call is skipped when the value is falsy or zero, maximizing execution speed but potentially increasing CPU usage and the risk of race conditions with slow-rendering applications.

### Where is the loop interval stored in the desktop application?

The desktop application persists this value in [`apps/ui-tars/src/main/store/setting.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/apps/ui-tars/src/main/store/setting.ts) with a default of `1000` milliseconds. This setting is retrieved via `SettingStore.getStore()` and passed to the SDK during agent initialization in [`apps/ui-tars/src/main/services/runAgent.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/apps/ui-tars/src/main/services/runAgent.ts).

### Can I change the loop interval during execution?

No, the `loopIntervalInMs` is read from the configuration at the start of each `guiAgent.run()` invocation. To modify the behavior dynamically, you must terminate the current run and create a new agent instance with updated configuration parameters.

### Why does the SDK default differ from the desktop app default?

The SDK defaults to `0` in [`packages/ui-tars/sdk/src/types.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/types.ts) to provide maximum flexibility for developers building custom implementations who may prioritize speed. The desktop application overrides this with `1000` ms to ensure out-of-the-box stability for end-users running on varied hardware who may prioritize reliability over raw execution speed.