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:

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" } }'

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.

Read it back to confirm it took:

curl "https://api.stateset.com/v1/agents/$AGENT_ID" \
  --header "Authorization: Bearer $STATESET_API_KEY"

Response

{
  "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_

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.

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 in front of the tool server.

The approvals queue

On suggest, a money-moving or irreversible action does not fail and does not wait in a chat thread — it lands in the approvals queue and the agent moves on. A human resolves it there.

GET /api/approvals/list?limit=	Pending approvals for the caller’s organization, with a suggestion for each. Any org key; 120 requests per minute.
POST /api/approvals/resolve	{ "approvalId": "…", "decision": "approved" | "denied" }. Admin only; 60 per minute.

Approving is the moment the money moves: the tool call executes through the same MCP handlers the agent sandbox uses, with the same guardrails. Denying records the decision and the agent’s next turn sees it.

The queue is not a table of its own. It is a view over the append-only audit_events ledger, so an approval, its resolution, and who resolved it are one immutable record — which is what makes the queue auditable after the fact rather than merely convenient before it.

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

ResponseCX platform

The platform this control governs.

Rules quickstart

Hard constraints, for behaviour no autonomy level should permit.

Agent Gate

Requiring a verified proof before a tool call runs.

Workflow Studio

Where the engine policy this sets is published from.