--- title: Manage the Agent lifecycle canonical: "https://agentbarn.dev/guides/agents/lifecycle" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-05T09:17:18.000Z" author: Agent Barn description: "Start, pause, restart, and retire an Agent in Agent Barn. Learn which changes need a restart and how to handle runtime failures separately from chat connection problems." tags: [Agents, How-to, "Agent operators, Agent editors, Agent owners, Organization administrators, and support engineers", Agent lifecycle, start Agent, pause Agent, stop Agent, restart Agent, Agent error, recover Agent, retire Agent, Apply and Restart, Agent status] categories: [Guides, Agents] --- Start an Agent when you want it to run, pause it when you want to stop its work, and retire it when you no longer need it. An Agent's runtime and its chat connections are managed separately. You can start an Agent before connecting it to Slack, Microsoft Teams, Telegram, or Discord. ## Before you begin You need access to the Agent and permission to perform the action: | Action | Permission you need | | --- | --- | | Start or pause | Agent Editor or Agent Owner access, or Organization Owner or Admin authority | | Change runtime configuration | Permission to update the Agent; changing credentials also requires permission to manage its secrets | | Retire | Agent Owner access, or Organization Owner or Admin authority | If an action is unavailable, ask an Organization Owner or Admin to review your access. See [Share access to an Agent](/guides/agents/sharing). ## Understand the Agent's state | Stored state | Meaning | Next action | | --- | --- | --- | | `STOPPED` | The Agent's runtime is stopped. The interface normally shows **Idle**. | Start the Agent when you want it to run. | | `RUNNING` | Agent Barn has started the runtime. Check runtime health to see whether it is ready to work. | Pause it, or apply configuration changes with **Apply & Restart**. | | `ERROR` | Starting the runtime failed. | Review the error, correct the cause, and try **Start** again. | The interface also uses health labels such as **Initializing**, **Working**, and **Needs attention**. These provide information about the runtime; they do not replace the stored lifecycle state. A chat connection has its own health status. A failed Slack connection, for example, does not by itself change the Agent's stored state to `ERROR`. ### What happens after hiring The web hire flow creates the Agent and then requests its start. You choose the runtime and behavior during hiring; you add chat connections afterward. If creation succeeds but starting fails, find the Agent in your Organization and review its state before trying to hire another one. If it is stopped or in `ERROR`, correct the problem and select **Start**. When using the API directly, creating an Agent leaves it `STOPPED`. Starting it is a separate request. ## Start an Agent 1. Open the Agent in Agent Barn. 2. If it is stopped or in `ERROR`, select **Start**. 3. Allow time for the runtime to initialize. 4. Review its runtime health. If it does not become ready, open its logs and check the reported error. Starting loads the Agent's selected Template or private override, assigned Skill versions, model configuration, and tool credentials into its runtime. An Agent does not need a chat connection to start. To receive messages from a chat service, add and configure a connection separately. See [Communication Connections](/guides/agents/communication-connections). ## Pause an Agent 1. Open a running Agent. 2. Select **Pause**. 3. Wait for the action to finish. The Agent becomes stopped and normally displays **Idle**. Pausing stops runtime processing, including scheduled runtime work. It preserves the Agent's saved configuration, persistent working data, connections, and history. Pausing does not disable or retire chat connections. Manage a connection separately if you want to change its availability. **Note** Agent Barn attempts to save a runtime log snapshot before stopping. This is best-effort: review important live logs before pausing if you need to retain them. ## Restart an Agent To restart the runtime manually: 1. Select **Pause** on the running Agent. 2. Wait until it is stopped. 3. Select **Start**. 4. Review runtime health and logs if startup does not complete successfully. **Warning** Restarting reloads the Agent's saved runtime configuration. It interrupts work, so choose a suitable time. If the Agent is already stopped or in `ERROR`, use **Start** directly. Pause is only available for a running Agent. ### Apply configuration changes | Agent state | Action | Result | | --- | --- | --- | | Stopped or `ERROR` | **Apply** | Saves the change. Start the Agent separately when ready. | | Running | **Apply & Restart** | Stops the runtime, applies the change, and starts it again. | Use this workflow for runtime settings such as the model, selected Template, assigned Skills, or tool credentials. After Apply & Restart, review both the saved configuration and runtime health. If an error is reported, inspect the Agent's current state before retrying. ### Change a chat connection Chat connection settings and credentials do not use the Agent restart workflow. Edit the connection itself; Agent Barn applies the change independently of the runtime. For a provider authentication or connectivity problem, inspect the affected connection and use its reconnect action where appropriate. Pausing and starting the Agent does not rebuild the provider session. See [Communication Diagnostics](/guides/observe-and-govern/communication-diagnostics). ## Recover from a problem Start by identifying which part failed: | What you see | What to inspect | What to do next | | --- | --- | --- | | Agent is in `ERROR` after Start | Reported startup error and runtime logs | Correct the cause, then select Start. | | Agent remains Initializing | Runtime logs and, for installation administrators, the Agent's Kubernetes workload | Resolve startup, image, storage, or capacity problems. | | Runtime becomes unhealthy while the Agent is still running | Runtime logs | Correct the cause; pause and start if a runtime restart is needed. | | Runtime is healthy but one chat service does not work | That connection's status, settings, and diagnostics | Fix the connection and reconnect it where appropriate. | | Messages work but Tool Calls are missing from Activity | The runtime telemetry path | Follow the Activity troubleshooting guidance. | Do not assume an Agent restart fixes every messaging problem. Runtime processing, chat delivery, and tool telemetry have separate failure paths. See [Review Agent health and logs](/guides/agents/health-and-logs) and [Observe Agent Activity](/guides/observe-and-govern/activity). ## Retire an Agent **Warning** Retire an Agent only when you no longer need it. There is no supported restore action. 1. Review any configuration or live logs you need to keep. 2. If a final stopped-session log snapshot matters, pause the Agent first. Snapshot capture is best-effort. 3. Open **Configuration**. 4. In **Danger zone**, select **Retire Agent**. 5. Review and confirm the retirement. Retirement removes the Agent from active use, removes its runtime resources, and retires its communication connections. Historical records may remain for cost attribution and related history, but the Agent cannot be restored through the interface. Retiring an Agent does not delete the external Slack app, Teams app, Telegram bot, or Discord bot. Manage those installations in their respective services. ## API reference Use these paths beneath: ``` /api/v1/organizations/{organization_id} ``` | Operation | Request | | --- | --- | | Create an Agent without starting it | `POST /agents` | | Read an Agent | `GET /agents/{agent_id}` | | Update a stopped Agent | `PATCH /agents/{agent_id}` | | Start | `POST /agents/{agent_id}/start` | | Pause | `POST /agents/{agent_id}/stop` | | Read runtime health | `GET /agents/{agent_id}/healthz` | | Retire | `DELETE /agents/{agent_id}` | `` Replace `{organization_id}` and `{agent_id}` with the IDs of your Organization and Agent. **Important** Requests require an authenticated user and the relevant permissions. Starting an already-running Agent, stopping an Agent that is not running, or directly updating runtime configuration while it is running returns a conflict. `` ## Next steps - [Configure an Agent](/guides/agents/configuration) - [Communication Connections](/guides/agents/communication-connections) - [Review Agent health and logs](/guides/agents/health-and-logs) - [Communication Diagnostics](/guides/observe-and-govern/communication-diagnostics) - [Observe Agent Activity](/guides/observe-and-govern/activity) - [Share access to an Agent](/guides/agents/sharing)