Skip to main content

Assign Autonomy Tiers

Tasks

Assign a T1–T4 autonomy tier to an agent identity so the built-in and custom policies that reference it enforce at the right level. Requires an admin role.

Assign a tier from the UI​

  1. Navigate to Identities and click the agent you want to assign a tier to.

  2. On the agent's detail page, use the Autonomy Tier selector to choose T1 (Human-directed), T2 (Semi-autonomous), T3 (Highly autonomous), or T4 (Fully autonomous). The selector is only shown for agent identities, not developers, and only admins can change it.

  3. The selection saves immediately — there's no separate save step. The badge next to the agent's name updates to reflect the new tier.

Assign a tier from the API​

Set the tier with a PUT request to the identity's autonomy-tier endpoint, authenticated with an admin personal access token:

curl -X PUT https://YOUR_ORG.aicontrols.dev/api/v1/identities/ns1%2Fagent-a/autonomy-tier \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tier": "T3"}'

The identity id must be URL-encoded — a namespace/name identifier like ns1/agent-a becomes ns1%2Fagent-a in the path. A successful response returns {"status":"ok","tier":"T3"}.

Clear back to the default​

Send an empty string to remove the explicit assignment — the agent then resolves to the default tier, T2 (Semi-autonomous):

curl -X PUT https://YOUR_ORG.aicontrols.dev/api/v1/identities/ns1%2Fagent-a/autonomy-tier \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tier": ""}'

From the UI, clearing works the same way — select the blank/default option in the tier selector.

What happens after​

The tier is cached and re-read by every replica roughly every 30 seconds, so a change takes effect fleet-wide within that window without requiring any restart.

Once it propagates, any policy referencing object.agent.autonomyTier or object.agent.autonomyLevel evaluates against the new value on the agent's next request — including the four built-in Autonomy Governance policies (see Autonomy Tiers) and any custom policy your team has written against those fields.

note

Changing an agent's tier does not retroactively change past audit events — only requests made after the change reflect the new tier.

See also​

Last updated on