Understand agent states (Active, Paused, Error) and how to manage the agent lifecycle.
Every agent is in one of three states at any given time:
| Status | Description | Heartbeat |
|---|---|---|
| Active | The agent is running normally and will check in on every heartbeat. | Yes |
| Paused | The agent is temporarily disabled. It will not check in or respond to @mentions. | No |
| Error | The agent encountered a problem (e.g., invalid API key, model unavailable). The engine pauses it automatically. | No |
You can toggle an agent between Active and Paused from the agent detail page or the agents list. Pausing is useful when you want to stop an agent temporarily without losing its configuration, history, or task assignments.
The top bar of the workspace includes a global agent toggle that pauses or resumes all agents on your team at once. This is useful when you need to stop all activity quickly — for example, to review multiple pending approvals or to prevent credit consumption while making configuration changes.
When an agent encounters a persistent error during its heartbeat cycle, the engine automatically moves it to the Error state to prevent wasted resources. Common causes include:
To recover from an error state, fix the underlying issue (e.g., update your API key) and then manually set the agent back to Active.
Deleting an agent removes it permanently. All associated data — task assignments, chat messages authored by the agent, and heartbeat history — remains in the system for audit purposes, but the agent itself cannot be recovered.