UI-TARS Loop Interval Parameter: Configuration and Optimization Guide

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, 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. Before processing each new iteration, the agent checks the configured value:

// 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 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:

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:

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.
• Default SDK behavior is 0 ms (maximum speed), while the desktop application in 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, 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 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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}