> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autonomy dial

> The one control for how far an agent acts on its own — draft, suggest or autopilot — and exactly what each level gates.

Every agent has an autonomy level. It is the single user-owned control for how
far the agent acts without a person, and it is read in three places: the
automation engine, the tool-call gate, and the sandbox.

| Level       | The agent                                                      | Confirmation required for                                    |
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
| `draft`     | Writes replies; a human sends them                             | **Every** non-read tool                                      |
| `suggest`   | **Default.** Sends and closes at high confidence; runs lookups | Money-moving and irreversible tools                          |
| `autopilot` | Acts without host-side confirmation                            | Nothing host-side — the in-sandbox policy gate still applies |

## What each level sets

The level maps to an engine policy rather than being interpreted ad hoc:

| Level       | Auto-send | Auto-close | Minimum confidence |
| ----------- | --------- | ---------- | ------------------ |
| `draft`     | no        | off        | —                  |
| `suggest`   | yes       | on         | 0.80               |
| `autopilot` | yes       | on         | 0.60               |

`autopilot` does not remove the confidence floor; it lowers it. An agent on
autopilot still declines to close a conversation it is not reasonably sure
about.

## Setting it

Autonomy lives on the agent, in `metadata.autonomy`:

```bash theme={null}
curl --request PUT "https://api.stateset.com/v1/agents/$AGENT_ID" \
  --header "Authorization: Bearer $STATESET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "metadata": { "autonomy": "draft" } }'
```

<Warning>
  An unrecognised value does not fail — it silently becomes `suggest`. So
  `"autonomy": "manual"`, `"off"` or a typo does not put the agent in draft; it
  puts the agent in the **middle** setting, sending replies and running lookups
  on its own. Read the value back after setting it, and treat "the dial did
  nothing" as evidence the value was rejected rather than applied.
</Warning>

Read it back to confirm it took:

```bash theme={null}
curl "https://api.stateset.com/v1/agents/$AGENT_ID" \
  --header "Authorization: Bearer $STATESET_API_KEY"
```

```json Response theme={null}
{
  "id": "agent_8Kx2mN4pQr",
  "agent_name": "Alex",
  "metadata": { "autonomy": "draft" }
}
```

## How a tool is judged money-moving

Under `suggest`, the confirmation gate fires for money-moving and irreversible
tools. A tool qualifies if it is on the platform's canonical destructive-tool
list, **or** if its name classifies as financial, destructive or bulk. Read
tools never qualify.

Classification is by substring on the tool name:

| Facet       | Matches names containing                                                        |
| ----------- | ------------------------------------------------------------------------------- |
| read        | `get_` `list_` `search_` `find_` `fetch_` `_info` `_details` `_stats` `_status` |
| bulk        | `batch_` `bulk_` `_all` `mass_`                                                 |
| destructive | `delete_` `remove_` `cancel_` `close_` `deactivate_` `disable_` `terminate_`    |
| financial   | `refund` `capture` `payment` `charge` `gift_card` `discount` `credit`           |
| write       | `create_` `update_` `add_` `set_` `modify_` `change_` `apply_` `assign_`        |

<Warning>
  **A custom tool whose name matches none of these is treated as not
  money-moving.** `void_invoice` contains no listed pattern, so under the
  default `suggest` level it runs with no confirmation — the gate never sees it
  as risky. If you register your own tools, either name them so they classify
  (`cancel_invoice`, `refund_order`) or put the agent on `draft`, where every
  non-read tool is gated regardless of its name.
</Warning>

<Note>
  On `autopilot` the host-side gate is off, but the sandbox's own policy gate
  still runs. Autopilot means "no confirmation prompts", not "no guardrails" —
  and if you want a proof that each call was authorized rather than a policy
  check you have to trust, put an [Agent Gate](/stateset-nsr-agent-gate) in
  front of the tool server.
</Note>

## Choosing a level

Start on `draft` while you are still reading what the agent writes. Move to
`suggest` once its replies are ones you would have sent — that is the level
most teams stay on, and the money-moving gate is what makes it safe to. Reach
for `autopilot` only where a wrong action is cheap to reverse, or where an
Agent Gate is proving each call.

## Next steps

<CardGroup cols={2}>
  <Card title="ResponseCX platform" icon="robot" href="/stateset-response/responsecx-platform">
    The platform this control governs.
  </Card>

  <Card title="Rules quickstart" icon="scale-balanced" href="/guides/rules-quickstart">
    Hard constraints, for behaviour no autonomy level should permit.
  </Card>

  <Card title="Agent Gate" icon="shield-halved" href="/stateset-nsr-agent-gate">
    Requiring a verified proof before a tool call runs.
  </Card>

  <Card title="Workflow Studio" icon="sliders" href="/stateset-response/responsecx-workflow-studio">
    Where the engine policy this sets is published from.
  </Card>
</CardGroup>