Learn when and how to pause an agent gracefully, what happens to in-flight runs, and the best practices for safely resuming an agent after maintenance.
Why you might pause an agent
There are several scenarios where pausing an agent is the right approach: you need to edit the system prompt or tools without affecting ongoing traffic; a downstream integration is experiencing an outage and you want to prevent a cascade of failures; you are migrating to a new model tier and want to test the change in staging first; or you are about to hit your monthly run quota and want to conserve the remaining runs for higher-priority agents. Pausing is non-destructive — the agent's configuration, logs, and history are fully preserved, and you can resume it at any time.
How to pause an agent
There are three ways to pause an agent. First, from the Agents list: click the three-dot menu next to the agent and select "Pause Agent". Second, from the agent detail page: click the status badge in the header (which shows "Active") and select "Pause" from the dropdown. Third, via the API: send a PATCH request to /v1/agents/{agentId} with the body {"status": "paused"}. In all three cases, Cotonity stops accepting new trigger events for the agent immediately. Any run already in progress at the time of pausing is allowed to complete, not terminated mid-flight, to avoid leaving data in an inconsistent state.
What happens to queued and in-flight runs
When an agent is paused, in-flight runs finish normally and their results are logged. Trigger events that arrive while the agent is paused are held in a queue for up to 1 hour by default (configurable to 0, 1, 6, or 24 hours under the agent's Settings → Pause Behavior). When the agent resumes, queued events are processed in order. If the queue retention is set to 0 hours, events arriving during the pause period are discarded. This is suitable for time-sensitive automations where a delayed response would be worse than no response — for example, real-time chat agents.
Safely resuming an agent
Before resuming a paused agent, review any changes you made to its configuration in the audit log (Settings → Audit Log) to confirm the intended edits are in place. If you changed the model tier, run a few test messages in the Test tab to verify the new model behaves as expected. When ready, click "Resume Agent" from the same menu or dropdown you used to pause it. The agent's status returns to Active immediately, and queued events begin processing. Monitor the Activity Log closely for the first few minutes after resuming to catch any unexpected errors introduced by your configuration changes.