Xagent Docs
Get started

Task Execution

This page explains how Xagent plans, executes, and completes a task from start to finish.

Execution Modes

How much planning a task does depends on its execution mode. Auto is the default — the agent picks the right approach for what you asked.

ModeWhat it doesBest for
Auto (default)Chooses one of the modes below for you.Most work — leave it here unless you have a reason not to.
FlashAnswers in a single pass, with no planning stage.Simple, direct questions.
BalancedAlternates thinking and acting, adjusting as it learns.Everyday multi-step work.
ThinkPlans the whole job as a step graph first, then executes it.Complex tasks with dependencies between steps.

The phases described below apply in full to Think mode. Lighter modes skip or compress the planning stage.

Execution Phases

1. Planning Phase

Xagent analyses your request, breaks the task into steps, identifies the tools needed, and generates a DAG (Directed Acyclic Graph) of the workflow.

  • Nodes — individual execution steps.
  • Edges — dependencies between steps.
  • Flow — execution order from start to finish.

2. Execution Phase

Steps run in dependency order. Tools are called automatically, results pass between steps, and progress updates in real time with step-by-step logging, error handling, retries, and dynamic adaptation.

3. Completion Phase

Results from all steps are aggregated into a final output, an execution summary is shown, and the task is saved for reference.

The Execution Interface

While a task runs you see the agent interface with a vertical step layout:

  • Chat area — your request, real-time status, the final result, and follow-up conversation.
  • Execution steps — each step shows its number and title, the agent's reasoning, inline tool calls and responses, and status indicators. Steps are expandable for detail.

Interacting with a Running Task

You are not locked out while a task runs:

  • Pause — stop work after the current step finishes. See Pausing and resuming.
  • Cancel — click the cancel/stop button to end execution. The current step completes, then execution stops and any partial results are saved.
  • Send follow-up messages — steer or refine the task mid-run from the chat area.
  • Upload additional files — attach more material for the agent to use while it works.

Task States

A task reports one of six states:

StateMeaning
PendingAccepted and queued, not started yet.
RunningActively working.
PausedStopped because you asked it to stop. Send a message to pick it back up.
Waiting for userThe agent stopped on its own because it needs an answer from you before it can continue. Reply and it resumes.
CompletedFinished successfully.
FailedStopped because of an error. The reason is shown on the task.

The difference between the two stopped states is who stopped it: Paused means you did, Waiting for user means the agent did because it has a question.

Pausing and Resuming

Pausing is a request, not an interruption. When you click Pause, the task acknowledges immediately and shows Pausing… while it finishes the step it is already on — nothing is abandoned half-done. Once that step completes, the state changes to Paused.

You will therefore see a short-lived intermediate state in the interface:

You seeWhat is happening
Pausing…Your pause was registered; the current step is wrapping up.
Resuming…Your resume was registered; work is being picked back up.

Messages sent while pausing

A message you send after clicking Pause but before the task has actually paused is not handed to the running agent. It is treated as a new turn once the task is paused — and sending it is itself enough to resume the task.

Why the task view stays in order

Xagent tracks which turn each update belongs to and versions every state change, so late or out-of-order updates are discarded rather than shown. That is why a paused task never flickers back to Running on your screen.

Tracking a Task

GET /api/chat/task/{task_id}
GET /api/chat/task/{task_id}/status
GET /api/chat/workspace/{task_id}/files
GET /api/chat/workspace/{task_id}/output

Real-time updates

Task progress is streamed over a WebSocket connection, so the interface reflects each planning and execution event as it happens. Pause, resume, and manual-intervention messages are also supported over the socket — see the WebSocket API.

Next Steps