Agent states
The six agent states the Agents API reports and the four coarse states they fold into.
Every agent the API lists or streams has a state. Agent events also carry a coarse_state, which folds the six states into four for clients that only care whether an agent is busy, needs someone or is gone.
| State | Meaning | Coarse state |
|---|---|---|
idle | Open, not working, nothing to see | idle |
working | In the middle of a turn | working |
waiting-for-input | Waiting for the user: a permission, a question or input | waiting-for-input |
done | Finished its turn and the user has not looked yet | idle |
exited | Its process ended; the tab is still there | closed |
closed | The tab or Worker is gone | closed |
Where states come from
Agents report through their vendor's hooks, and the app turns each report into a state: a prompt submitted or a tool run means working, a permission asked means waiting for input, a turn finished means done. The done state lasts until the user looks at the agent. See Agents bus.
Reasons
An agent event names the reason for a change when the app knows it:
| Reason | The change |
|---|---|
turn_started | A turn began |
turn_finished | A turn ended |
ask_pending | The agent waits on an ask, such as a question or a plan |
permission_pending | The agent waits on a permission |
input_pending | The agent waits for input |
process_exited | The agent's process ended |
user_closed | The user closed the tab |
environment_closed | Its environment closed |
Waiting on a state
Wait blocks until a terminal stops working and answers the state it settled in. A terminal the app is still starting counts as working.
{"Wait":{"target":4,"timeout_secs":600}}
{"Settled":{"target":4,"state":"done"}}With the CLI, krad wait 4 exits with 0 once the agent settles and with 3 when the wait times out.