# UI-TARS-desktop | Bytedance Inc. | Knowledge Base | Instagit

The Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra

GitHub Stars: 31.6k

Repository: https://github.com/bytedance/UI-TARS-desktop

---

## Articles

### [StatusEnum States in the UI-TARS Agent Lifecycle: Complete Reference](/bytedance/UI-TARS-desktop/what-are-statusenum-states-in-agent-lifecycle)

Explore the eight StatusEnum states like INIT, RUNNING, and ERROR that define the UI-TARS Agent lifecycle from start to finish. Understand agent behavior and transitions.

- Tags: api-reference
- Published: 2026-05-10

### [How UI-TARS Handles User‑Initiated Stops During Agent Execution](/bytedance/UI-TARS-desktop/how-does-agent-handle-user-initiated-stops-during-execution)

Learn how UI-TARS desktop handles user initiated stops. The agent sets a stopped flag in AgentContext to break the execution loop and emit a TASK_CANCEL event.

- Tags: internals
- Published: 2026-05-10

### [UITarsModelVersion and Provider Selection Relationship in UI-TARS Desktop](/bytedance/UI-TARS-desktop/relationship-between-uitarsmodelversion-and-provider-selection)

Understand the UITarsModelVersion and provider selection relationship in UI-TARS Desktop. Learn how VLMProviderV2 maps to model versions with fallback options.

- Tags: deep-dive
- Published: 2026-05-10

### [How to Set Up a Custom Report Storage Server for HTML Exports in UI-TARS](/bytedance/UI-TARS-desktop/how-to-set-up-custom-report-storage-server-for-html-exports-in-ui-tars)

Learn how to set up a custom Report Storage Server for UI-TARS HTML exports. Implement a POST endpoint to store reports and activate automated uploads via Report Settings.

- Tags: how-to-guide
- Published: 2026-05-10

### [UI-TARS Coordinate Transformation: 3 Factors Driving Normalization Calculations](/bytedance/UI-TARS-desktop/what-are-factors-for-coordinate-transformation-calculations-in-ui-tars)

Discover the 3 key factors driving UI-TARS coordinate transformation calculations: raw input, NormalizeCoordinates function, and screenshot dimensions for accurate scaling.

- Tags: deep-dive
- Published: 2026-05-10

### [How the Model Invoke Retry Mechanism Handles API Errors in UI-TARS Desktop](/bytedance/UI-TARS-desktop/how-does-model-invoke-retry-mechanism-handle-api-errors)

Learn how the UI-TARS desktop SDK uses async-retry for its model invoke retry mechanism to handle API errors, automatically retrying failed requests and distinguishing transient errors from user aborts.

- Tags: how-to-guide
- Published: 2026-05-10

### [How to Implement Custom System Prompts for Specific UI-TARS Use Cases](/bytedance/UI-TARS-desktop/how-to-implement-custom-system-prompts-for-specific-ui-tars-use-cases)

Learn to implement custom system prompts for UI-TARS use cases. Customize GUIAgent, Operators, or SYSTEM_PROMPT_TEMPLATE for tailored interactions.

- Tags: how-to-guide
- Published: 2026-05-10

### [How Screenshot Retry Logic Works in UI-TARS Desktop: Configuration and Customization Guide](/bytedance/UI-TARS-desktop/what-is-screenshot-retry-logic-and-how-to-customize-it)

Learn how UI-TARS Desktop's screenshot retry logic handles failures with async-retry. Customize retry attempts and callbacks using the RetryConfig interface for robust UI automation.

- Tags: how-to-guide
- Published: 2026-05-10

### [How the Browser Operator Handles Search Engine Configurations in UI-TARS](/bytedance/UI-TARS-desktop/how-does-browser-operator-handle-different-search-engine-configurations)

Discover how UI-TARS desktop handles search engine configurations. Learn how DefaultBrowserOperator and RemoteBrowserOperator manage different search engines like Google Bing and Baidu.

- Tags: how-to-guide
- Published: 2026-05-10

### [UI-TARS Loop Interval Parameter: Configuration and Optimization Guide](/bytedance/UI-TARS-desktop/what-is-loop-interval-parameter-and-when-to-adjust-it)

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.

- Tags: how-to-guide
- Published: 2026-05-10

### [How to Configure the Responses API for Reduced Token Consumption in UI-TARS](/bytedance/UI-TARS-desktop/how-to-configure-responses-api-for-reduced-token-consumption)

Reduce token consumption with UI-TARS Responses API. Enable useResponsesApi: true and set max_tokens for efficient message handling and automatic pruning.

- Tags: performance
- Published: 2026-05-10

### [Error Status Types in UI-TARS: Complete Handling Guide for GUI Agent Failures](/bytedance/UI-TARS-desktop/what-are-error-status-types-in-ui-tars-and-how-to-handle-them)

Master UI-TARS error status types with our complete handling guide. Learn to manage GUI agent failures using ErrorStatusEnum and GUIAgentError for robust recovery.

- Tags: how-to-guide
- Published: 2026-05-10

### [How the UTIO Event System Tracks Application Usage in UI-TARS Desktop](/bytedance/UI-TARS-desktop/how-does-utio-event-system-track-application-usage)

Discover how the UTIO event system tracks application usage in UI-TARS Desktop, capturing lifecycle events and user interactions via a typed telemetry layer. Learn more.

- Tags: internals
- Published: 2026-05-10

### [Understanding Max Loop Count Behavior in UI-TARS Desktop: Preventing Premature Termination](/bytedance/UI-TARS-desktop/what-is-max-loop-count-behavior-and-how-to-prevent-premature-termination)

Learn how to prevent premature termination by understanding max loop count behavior in UI-TARS Desktop. Override settings and manage abort signals for uninterrupted agent execution.

- Tags: deep-dive
- Published: 2026-05-10

### [How the Event Streaming Protocol Drives Context Engineering in UI-TARS](/bytedance/UI-TARS-desktop/how-does-event-streaming-protocol-drive-context-engineering-in-ui-tars)

Discover how the UI-TARS Desktop event streaming protocol structures agent execution data into multimodal context, enhancing context engineering with a three-layer pipeline.

- Tags: deep-dive
- Published: 2026-05-10

### [VLM Providers Available in UI-TARS Desktop and Their Impact on Action Parsing](/bytedance/UI-TARS-desktop/which-vlm-providers-are-available-and-how-do-they-affect-action-parsing)

Discover the VLM providers in UI-TARS Desktop: Hugging Face and VolcEngine Ark. Learn how they impact action parsing and agent output grammar for better results.

- Tags: deep-dive
- Published: 2026-05-10

### [How to Implement a Custom Operator Class for UI-TARS SDK](/bytedance/UI-TARS-desktop/how-to-implement-custom-operator-class-for-ui-tars-sdk)

Learn how to implement a custom Operator class for the UI-TARS SDK. Extend the abstract Operator class and implement screenshot and execute methods for custom UI automation.

- Tags: how-to-guide
- Published: 2026-05-10

### [Difference Between Local and Remote Operators in UI-TARS Desktop: Implementation Guide](/bytedance/UI-TARS-desktop/difference-between-local-and-remote-operators-in-ui-tars-desktop)

Understand the difference between local and remote operators in UI-TARS Desktop. Learn how each manages browser instances for efficient UI testing.

- Tags: how-to-guide
- Published: 2026-05-10

### [How UI-TARS Session Management and UUID Generation Works](/bytedance/UI-TARS-desktop/how-does-ui-tars-session-management-and-uuid-generation-work)

Discover how UI-TARS session management and UUID generation leverage IndexedDB and RFC-4122 v4 UUIDs to store conversations effectively. Learn the technical details now.

- Tags: internals
- Published: 2026-05-10

### [UI-TARS Desktop Internal Action Space Types and Agent Loop Processing Explained](/bytedance/UI-TARS-desktop/what-are-internal-action-space-types-and-agent-loop-processing)

Discover UI-TARS Desktop's internal action types call user, max loop, error env, and finished. Learn how GUIAgent run() orchestrates screenshot capture, LLM inference, and execution cycling.

- Tags: internals
- Published: 2026-05-10

### [How Scale Factors Impact Coordinate Mapping in UI-TARS Desktop](/bytedance/UI-TARS-desktop/how-do-scale-factors-impact-coordinate-mapping-in-ui-tars-desktop)

Discover how scale factors in UI-TARS Desktop map logical coordinates to physical screen coordinates using DPR for precise automation on high-DPI displays.

- Tags: deep-dive
- Published: 2026-05-10

### [UI-TARS SDK Retry Mechanism: How to Configure Retries for Screenshots, Models, and Actions](/bytedance/UI-TARS-desktop/what-is-ui-tars-sdk-retry-mechanism-and-how-to-configure-it)

Learn about the UI-TARS SDK retry mechanism and configure retries for screenshots, models, and actions. Master asynchronous retries for robust UI automation.

- Tags: how-to-guide
- Published: 2026-05-10

### [How to Pause and Resume GUIAgent Execution in UI-TARS Desktop](/bytedance/UI-TARS-desktop/how-to-pause-and-resume-guiagent-execution-in-ui-tars-desktop)

Effortlessly pause and resume GUIAgent execution in UI-TARS Desktop using simple guiAgent.pause() and guiAgent.resume() commands. Control your test flow with ease.

- Tags: how-to-guide
- Published: 2026-05-10