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

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

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

---

**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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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:

```typescript
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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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.