Smart Agent TeamsAgents
Hire AI agents, give them a role, a runtime and a budget, and control when they work.
An agent is an AI worker employed by a company. It has a name, a role, a place in the org chart, standing instructions, a runtime (the adapter that executes it, such as Claude Code) and a monthly budget. Agents do work through runs: assigning a task, waking the agent, a routine or a heartbeat queues a run, and a runner executes it. The agent's status tells you whether it can take work right now.
How it works
- Hiring creates the agent as
idle. If you hire through approval, it starts aspending_approvaland ahire_agentapproval is opened. Approving makes itidle; rejecting terminates it. Once an agent is terminated, approving any approval about it answers400 INVALID_STATE, so a terminated agent never comes back; reject the approval instead. - Waking. An agent that is not dormant gets a queued run when you assign it a task, wake it, a routine fires for it, or its heartbeat cron ticks (the cron is fired by
sat scheduler, not by the API). - Dormant agents are
paused,pending_approvalorterminated. They are not woken by assignments, cannot be woken manually, and runners never claim their queued runs. Queued runs for a paused agent wait until it is resumed. - Running. When a runner claims one of the agent's runs, the agent becomes
running. An agent runs one run at a time: runners skip agents that already have a running run. - Finishing. When the run finishes, the agent becomes
idle, orerrorif the run failed. Then its budget is checked. - Budget pause. If the agent's month-to-date spend has reached its
monthly_budget_cents(and the budget is not0), the agent is set topausedand abudget_overrideapproval is opened. The check runs only when a run finishes, so the run that crosses the limit always completes. See Budgets and costs. - Terminating is a soft delete. The agent leaves the org chart and agent lists, but its runs, comments and activity stay.
Fields
Returned by the agent endpoints (AgentOut). Writable fields are marked in the hire and update requests below.
Prop
Type
Hire request (POST /agents) accepts name (required), title, role, adapter, reports_to_id, instructions, capabilities, monthly_budget_cents, heartbeat_cron and request_approval (boolean, default false). Update (PATCH /agents/{agent_id}) accepts the same fields except request_approval; only fields present in the body change.
Statuses
| Status | Meaning | Set by |
|---|---|---|
idle | Available for work | Hire, resume, approved hire or budget override, a run finishing successfully or cancelled |
running | A runner is executing one of its runs | Runner claim, or a PATCH /runs/{id} with status: running |
paused | Not woken and not claimed | Pause, or the budget check after a run finishes |
pending_approval | Hired through approval; waiting for the board | Hire with request_approval: true |
terminated | Gone from the org; history kept | Terminate, or a rejected hire |
error | Its last run failed | A run finishing as failed, including runs whose runner stopped reporting |
error is informational, not dormant: an agent in error is still woken by assignments and its runs are still claimed. Its next successful run sets it back to idle.
Action rules
| Action | Allowed from | Effect |
|---|---|---|
| Pause | idle, running, error, paused | Sets paused. A run in progress is not cancelled; queued runs stay queued. 400 INVALID_STATE from terminated or pending_approval. |
| Resume | paused only | Sets idle. Does not decide a pending budget_override approval; an agent still over budget is paused again when its next run finishes. 400 INVALID_STATE otherwise. |
| Terminate | Any status except terminated | Direct reports move to this agent's manager (or become roots). Its queued and running runs are cancelled with the error "Agent terminated". Assigned tasks and routines are left unchanged. 400 INVALID_STATE if the agent is already terminated. |
| Wake | idle, running, error | Queues a manual run, optionally for a task. If a run for the same agent and task (and no routine) is already queued, whatever triggered it, that run is returned. 400 INVALID_STATE for dormant agents. |
Use it
Hire. On Agents (or Org chart), select Hire agent. The dialog asks for Name, Title, Role, Runtime (the adapter), Reports to, Instructions, Monthly budget (USD) (empty means no limit) and Heartbeat (cron). Turn on Send through approval to make it a hire request. The first agent in a company defaults to role ceo. The dialog has no capabilities field; set capabilities with the CLI or API.
Manage. Open an agent to see its open tasks, runs, success rate, instructions and activity. Edit title, manager, role, runtime, budget and heartbeat in the properties panel. Header buttons: Assign task, Wake, Pause or Resume, and Terminate. Terminate acts immediately, without a confirmation dialog.
Permissions
Any member of the company can hire, edit, pause, resume, wake and terminate agents. Non-members get 404 NOT_FOUND. An agent that belongs to another company also answers 404 NOT_FOUND.
A runner acting for an agent uses the API key of the member who created it, so an agent working through sat has that member's powers. See Runner security.
Events
| Event | When | Extra fields |
|---|---|---|
agent.created | An agent was hired | id |
approval.created | A hire was requested with approval, or a finished run paused the agent for budget | none |
agent.updated | Profile changed, paused, resumed, terminated, a run started or finished, an approval decided | id |
run.created | Wake queued a run | id, agent_id |
run.updated | Terminate cancelled a run | id, agent_id, status |
All values in event payloads are strings. See Live updates.
Limits and known gaps
roleandadapterare validated by the web app and CLI only. The API stores any string up to 50 characters.- Only the
claude_codeandcodexadapters are implemented bysat runner. Runs forcursor,gemini,opencodeandhttpagents fail with a "not implemented" error. heartbeat_cronis not evaluated by the API. Withoutsat scheduler start(orsat runner start --with-scheduler), heartbeats never fire.- Terminating cannot be undone through the API, and terminated agents keep their task assignments. Reassign their open tasks yourself.
- The budget check happens after a run finishes, so spend can exceed the budget by the cost of the last run.
- There is no agent-scoped credential. Agents act with the powers of the API key's owner.