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.
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
- Open the Agent in Agent Barn.
- If it is stopped or in
ERROR, select Start. - Allow time for the runtime to initialize.
- 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.
Pause an Agent
- Open a running Agent.
- Select Pause.
- 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.
Restart an Agent
To restart the runtime manually:
- Select Pause on the running Agent.
- Wait until it is stopped.
- Select Start.
- Review runtime health and logs if startup does not complete successfully.
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.
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 and Observe Agent Activity.
Retire an Agent
- Review any configuration or live logs you need to keep.
- If a final stopped-session log snapshot matters, pause the Agent first. Snapshot capture is best-effort.
- Open Configuration.
- In Danger zone, select Retire Agent.
- 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.