StatusEnum States in the UI-TARS Agent Lifecycle: Complete Reference

The UI-TARS desktop client defines eight distinct StatusEnum states—INIT, RUNNING, PAUSE, END, CALL_USER, MAX_LOOP (deprecated), USER_STOPPED, and ERROR—to model the complete lifecycle of autonomous GUI agents from instantiation through termination.

The StatusEnum type definition in the bytedance/UI-TARS-desktop repository governs how the autonomous agent transitions through its operational workflow. Located in the shared types package, this enum provides the canonical state machine that coordinates execution flow, user interactions, and error handling across the desktop client.

StatusEnum Definition Location

The canonical definition resides in packages/ui-tars/shared/src/types/agent.ts. This file exports the StatusEnum type used throughout the agent's core logic to enforce type-safe state transitions.

A historical copy exists in multimodal/gui-agent/shared/src/types/archived.ts for backward compatibility. This archived variant contains the same lifecycle states but omits the deprecated MAX_LOOP value, reflecting an earlier iteration of the state machine.

The Eight StatusEnum States Explained

The agent lifecycle progresses through the following distinct states defined in the enum:

• INIT — The agent has been instantiated but has not yet started execution. This represents the initial idle state before the automation loop begins.

• RUNNING — The agent is actively processing requests and performing GUI actions. This state indicates busy execution where the agent is driving interactions autonomously.

• PAUSE — Execution is temporarily suspended, typically awaiting user interaction or an external event before resuming. Unlike terminal states, PAUSE implies potential continuation.

• END — The agent has completed its task successfully or reached a natural termination point. This represents a clean exit from the automation workflow.

• CALL_USER — The agent explicitly requests user input or confirmation before proceeding. This state triggers UI prompts that require human intervention to continue.

• MAX_LOOP — (Deprecated) A legacy value retained for backward compatibility. Originally represented hitting a maximum iteration limit, but current implementations handle loop limits through other mechanisms.

• USER_STOPPED — Indicates the user manually interrupted or stopped the agent before normal completion. This distinguishes intentional cancellations from natural terminations.

• ERROR — An unrecoverable error has occurred, placing the agent in a failure state. When entered, the agent ceases execution and typically surfaces error details to the user interface.

Implementing Status Checks in TypeScript

The following pattern demonstrates how to import StatusEnum and handle state transitions in application logic:

import { StatusEnum } from '@/packages/ui-tars/shared/src/types/agent';

function handleAgentStatus(status: StatusEnum) {
  switch (status) {
    case StatusEnum.INIT:
      console.log('Agent is initializing...');
      break;
    case StatusEnum.RUNNING:
      console.log('Agent is running.');
      break;
    case StatusEnum.PAUSE:
      console.log('Agent is paused, awaiting user action.');
      break;
    case StatusEnum.CALL_USER:
      console.log('Agent needs user input.');
      break;
    case StatusEnum.END:
      console.log('Agent has completed its task.');
      break;
    case StatusEnum.USER_STOPPED:
      console.log('Agent was stopped by the user.');
      break;
    case StatusEnum.ERROR:
      console.error('Agent encountered an error.');
      break;
    default:
      console.warn('Unknown agent status:', status);
  }
}

// Simulate a state transition
let currentStatus: StatusEnum = StatusEnum.INIT;
currentStatus = StatusEnum.RUNNING;
handleAgentStatus(currentStatus);

Consuming code typically checks StatusEnum values to determine UI visibility, enable or disable controls, and manage cleanup routines when the agent reaches terminal states like END, USER_STOPPED, or ERROR.

UI Components Reflecting Agent Status

The StatusEnum drives visual status indicators throughout the application interface. Two key components consume these states:

• multimodal/websites/main/src/render/components/StatusBar.tsx — Renders the current agent status in the main application chrome, displaying human-readable labels mapped to the enum values.

• multimodal/tarko/ui/src/components/code-editor/CodeEditorStatusBar.tsx — Provides status feedback within the code editor context, allowing developers to monitor agent execution without leaving the editing environment.

These components import StatusEnum from the shared types package to ensure consistency between internal state management and visual feedback presented to users.

Summary

• StatusEnum in packages/ui-tars/shared/src/types/agent.ts defines the complete agent lifecycle with eight possible states.
• INIT and RUNNING represent pre-execution and active execution phases.
• PAUSE and CALL_USER indicate execution interruptions requiring external input or temporary suspension.
• END and USER_STOPPED distinguish between natural completion and manual termination.
• ERROR handles unrecoverable failures, while MAX_LOOP provides backward compatibility for legacy loop-limit logic.
• UI components like StatusBar.tsx consume these states to provide real-time execution feedback.

Frequently Asked Questions

What is the difference between PAUSE and CALL_USER states?

The PAUSE state represents a temporary execution suspension where the agent may resume automatically or await a system event, while CALL_USER specifically indicates that the agent requires explicit human input or confirmation before it can proceed. The distinction helps UI logic determine whether to show general wait indicators versus interactive input dialogs.

Where is StatusEnum defined in the UI-TARS codebase?

The primary definition resides in packages/ui-tars/shared/src/types/agent.ts according to the source code structure. A secondary archived copy exists in multimodal/gui-agent/shared/src/types/archived.ts for historical reference, though this version excludes the deprecated MAX_LOOP state.

What happens when an agent enters the ERROR state?

When StatusEnum.ERROR is set, the agent immediately ceases all automation activities and enters a terminal failure state. As implemented in the UI-TARS desktop client, this state triggers error handling routines that typically surface failure details to the user interface and prevent further state transitions until the agent is reset or reinitialized.

Is the MAX_LOOP state still used in current versions?

No, MAX_LOOP is marked as deprecated and retained solely for backward compatibility. Current versions of the UI-TARS agent handle iteration limits through internal counters and other state transitions rather than exposing a dedicated enum value for loop conditions. New implementations should not rely on this state for production logic.

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