> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pause, steer and resume a running AI agent workflow

> Pause a running agent workflow from the terminal, change its mode or send it new instructions, then resume it from the same point and check how it ended.

An agent that heads the wrong way costs time and tokens for as long as it keeps going. In this guide you start an agent run, pause it in the middle of a command, change its mode, give it a new instruction and resume it, so it finishes the task you meant. A run keeps its whole state while it is paused, so it continues from where it stopped instead of starting over. Every control is described in [Workflow control](https://docs.reliantlabs.io/workflows/workflow-control.md).

## Before you begin

* The `reliant` CLI, v1.21 or later, signed in ([Sign in and tokens](https://docs.reliantlabs.io/cli/sign-in.md)).
* A connected machine that holds the repository ([Run a machine from the terminal](https://docs.reliantlabs.io/cli/run-a-machine.md)).
* The Reliant app open on the same account, for the steps that change a running agent. The CLI pauses, resumes and reads runs; messages and parameter changes are sent from the app.

**1. Start a run**

Any workflow run works, including one an [automation](https://docs.reliantlabs.io/automations/overview.md) started. This one asks the stock agent for a small change with a slow command in the middle:

```bash terminal theme={null}
reliant workflow run agent --project-path . \
  --message "Add a docstring to every function in calc.py, then run 'sleep 60' in the shell before you write tests for calc.py with unittest and run them with python3 -m unittest."
```

```text theme={null}
Workflow "agent" triggered
  Chat/Execution ID: 5de105c6-6281-45ec-ba28-21bb38c3569a
  Title:             agent · Add a docstring to every function in calc.py, then run 'sle… (listed under Runs)
```

The execution ID is the run's chat ID. Every command below takes it. Runs started from the CLI are listed under **Workflows → Runs** in the app.

**2. Pause it**

```bash terminal theme={null}
reliant workflow pause 5de105c6-6281-45ec-ba28-21bb38c3569a
reliant workflow status 5de105c6-6281-45ec-ba28-21bb38c3569a
```

```text theme={null}
Paused workflow 5de105c6-6281-45ec-ba28-21bb38c3569a (Chat paused successfully)
Execution 5de105c6-6281-45ec-ba28-21bb38c3569a
  Workflow:  builtin://agent
  Status:    PAUSED
  Open questions: 0   Open approvals: 0

STEP EXECUTIONS  (by node thread)
  (root)  ← builtin://agent
    STEP                     ACTIVITY                RUNS FAILED  LAST      LAST(ms)
    call_llm                 CallLLM                    2         ok        2628
    execute_tools            ExecuteTools               2         ok        22062
```

Pausing stops work in flight first. The `sleep 60` was 22 seconds in, and the agent's shell call ended with `Tool execution cancelled`. In the app, the stop button in the composer and `Esc` do the same.

**3. Steer it while it is paused**

In the app, open the run and change what you need before it continues:

* **Mode or model.** Switch the mode in the composer toolbar, for example from `auto` to `plan`, which leaves the agent read-only tools. Pick another model with the model button. A change applies at the agent's next model call.
* **A new instruction.** Type it in the composer. Sending a message to a paused run resumes it with your message added. To leave the run paused for now, resume from the terminal instead (next step) and send the message once it runs: a message sent to a running agent is queued, and the agent reads it at its next turn.

For this run, the mode went to `plan` and the message was: *Change of plan: skip the sleep and don't write tests. Tell me in one line what calc.py does.*

**4. Resume it**

```bash terminal theme={null}
reliant workflow resume 5de105c6-6281-45ec-ba28-21bb38c3569a
reliant workflow watch 5de105c6-6281-45ec-ba28-21bb38c3569a
```

```text theme={null}
Resumed workflow 5de105c6-6281-45ec-ba28-21bb38c3569a (Chat resumed successfully)
16:09:18  ▶ node call_llm started
16:09:20  ✓ node call_llm completed
16:09:20  ✓ workflow completed
```

`watch` blocks and prints each boundary as it happens: nodes, questions, approvals, and the end of the run. `reliant workflow follow` streams the same events as JSON, for scripts.

**5. Verify the run took the new direction**

`reliant workflow status` shows `Status: COMPLETED`, and the run's last replies in the app show the agent working from the new settings:

```text theme={null}
Tests: not written and not run. This session is in planning mode, which doesn't allow file changes …
`calc.py` has two functions: `add(a, b)` returns the sum of `a` and `b`, and `mul(a, b)` returns their product.
```

The agent noticed the switch to `plan`, did not rerun the cancelled `sleep`, and answered the queued message. `git status` shows only the docstring edit it made before the pause.

## When a run pauses by itself

A step of the main agent that fails after its retries pauses the run instead of failing it. The chat says what failed, such as an expired provider login, and ends with "Workflow paused — send a message to retry". Fix the cause, then send a message or run `reliant workflow resume`. Runs nobody is watching, such as automations, retry by themselves for about half an hour before they end as failed. [Automatic pause on failure](https://docs.reliantlabs.io/workflows/workflow-control.md#automatic-pause-on-failure) covers both cases, and sub-agents.

## What this does not do

* **Pausing is not stopping.** A paused run keeps its checkpoint and still counts against its workflow's `concurrency.max_running`. To end a run for good, run `reliant workflow terminate <execution-id>` or **Stop** on the run's page. A terminated run cannot be resumed.
* **A cancelled command is not rerun for you.** Pausing cancels the command in flight. After you resume, the agent decides whether to run it again, so say so in your message if you want it rerun.
* **The CLI cannot message a run or change its parameters.** Use the app's composer for both, or a sub-agent's own message box to steer just that sub-agent ([Messaging a running workflow](https://docs.reliantlabs.io/workflows/workflow-control.md#messaging-a-running-workflow)).

## Next steps

> [card] [Workflow control](https://docs.reliantlabs.io/workflows/workflow-control.md)
>
> Every pause, resume and steering control, in the app and the terminal.

> [card] [Require human approval](https://docs.reliantlabs.io/guides/workflows/require-human-approval.md)
>
> Make a run stop and wait for you at a fixed point instead.

> [card] [How workflows run](https://docs.reliantlabs.io/deep-dives/how-workflows-run.md)
>
> Why a paused run costs nothing and continues where it stopped.

> [card] [First multi-agent workflow](https://docs.reliantlabs.io/guides/workflows/first-multi-agent-workflow.md)
>
> Write a workflow of your own to run, pause and steer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.