Autonomy tiers
How far an agent runs on its own is not a fixed property of the agent. It is the autonomy tier, chosen for a run. The same agent can pause on its plan and wait for you, or run its plan through without interruption, depending on the tier you put it in. This page explains the four tiers, what the tier actually changes, and how to choose one. For the safeguards and the step budget that bound every run regardless of tier, see the accountability model; this page is the companion that explains the tier, not the guardrails.
The tier, not the agent
Separating "what the agent can do" from "how far it may go unattended" is the key idea, and the tier only ever answers the second half. The sheet of an agent grants its tools; the tier decides whether its plan waits for approval and whether its result is verified afterwards. It decides nothing about permissions: no tier grants a tool, refuses one, or adds a human checkpoint to a tool call. That separation is what lets you deploy the same agent conservatively in a sensitive context and loosely on an isolated test machine, without rewriting it.
The four tiers
Apollia defines four tiers, from most supervised to most autonomous:
- Assisted. The default. The gate is active: a proposed plan waits for a human decision before it executes. This is the tier for unfamiliar agents, sensitive data, or any run where you want to see the plan before it executes. The gate is a plan gate and nothing else; it adds no checkpoint to an individual tool call.
- Supervised. The gate is still active, and this is the tier from which the runtime's own verification pass turns on (see below). Use it when you want the plan gate plus the engine's self-checking.
- Bounded autonomous. The gate is bypassed: the agent acts without pausing for plan approval, within the runtime's non-bypassable budget. Use it for trusted, well-scoped work where interruption would cost more than it protects.
- Long autonomous. Also gate-bypassed, intended for longer unattended runs. This is the widest tier, appropriate only when the task is well understood and the budget and permissions already constrain the blast radius.
Both effects apply to the run of an agent, and an agent is data: an [[agents]]
entry in the apollia.toml of its package, or an agent created in the
application, run by the engine built into the runtime. No Python of a package
chooses an execution path. The tier an agent runs at is the one its package
recommends (autonomy, under [agents.defaults]), then the override of the
person, then the global default, and the verification pass is attached to the run
from Supervised upward. Whether the agent writes a plan before acting is a
separate setting, its planning mode (planning: never, auto or always), and
a plan written that way has no approval of its own: approving a plan before it
executes belongs to the plan mode of a conversation.
The gate is active in Assisted and Supervised, and bypassed in Bounded autonomous
and Long autonomous, but only for a run that carries no decision of its own.
apollia-os run always carries one: --plan arms the gate for that run and its
absence disarms it, whichever tier the run is in. Moving up the tiers trades
interruption for momentum.
What the tier actually changes
Four things move with the tier, and no others. The plan gate: in the two lower tiers a consequential plan pauses for human approval, in the two higher tiers it does not, and in both cases a run that carries its own decision overrides the tier. Self-checking: the runtime's verification and critic pass is dark in Assisted and comes into play from Supervised upward, so a completed run can be checked before its result is accepted. The system-prompt profile: Assisted takes one built-in prompt, the three other tiers take a more persistent one. And the suggested step budget, which is the one worth reading twice.
The four tiers declare 100, 200, 300 and 500 reasoning steps, and that table is real. What reads it is the chat path, and free chat runs at the default tier and never varies.
An agent run reads that table too. It takes the budget of the tier the agent runs at and caps it against a fixed runtime ceiling of 100 reasoning steps, 200 tool calls and 1200 seconds of wall clock. So raising the tier widens what an agent may attempt well before it changes what the agent actually gets, and it never removes the hard edge. The mechanics of the verification loop belong to the plan and orchestrated execution model, and the safeguards it runs under belong to the accountability model.
Choosing a tier
Choose by the cost of a wrong action and the trust the task has earned. Start new or sensitive work in Assisted, where you see the plan first. Move to Supervised when you want the engine's verification without giving up the gate. Reach for the autonomous tiers only when the work is well scoped, the permissions are tight, and the interruptions of a lower tier would cost more than they protect. The tier is easy to change, so treat it as a per-run judgment, not a permanent setting.
The tier of an agent is set on the agent:
apollia-os agent set <AGENT_ID> autonomy <tier> overrides what its package
recommends, and apollia-os run takes --autonomy for one run. There is no
[autonomy] section in apollia.toml that the runtime reads, and the desktop
offers no control that changes the tier.