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.

note

An identity bound to a registered workload takes its tier from the workload: its Blueprint's tier, or its override's. You can't assign it a tier here. Change the tier on the Blueprint or in the workload's override instead. The API returns 409 Conflict for an assignment to such an identity. See Where the tier comes from.

Assign a tier from the UI​

  1. Navigate to Inventory → 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/autonomy-tier?id=ns1%2Fagent-a" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tier": "T3"}'

The identity id is passed as a URL-encoded query parameter, not a path segment — a namespace/name identifier like ns1/agent-a becomes id=ns1%2Fagent-a. 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/autonomy-tier?id=ns1%2Fagent-a" \
  -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.

Resolve a tier conflict​

If an identity had an assigned tier before you registered its workload, and the two tiers differ, the stricter (lower) tier applies until you choose one. The Identities page lists these conflicts.

  1. Open the identity from the conflict list on Inventory → Identities.

  2. Under Autonomy tier conflict, choose Use the workload's tier to clear the assigned tier, or Keep the assigned tier in the workload's override to move it to the workload.

From the API, send {"keep": "workload"} or {"keep": "assigned"}:

curl -X POST "https://YOUR_ORG.aicontrols.dev/api/v1/identities/autonomy-tier/resolve?id=IDENTITY_ID" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keep": "workload"}'

Clearing the assigned tier with a PUT and an empty tier also accepts the workload's tier. Each resolution writes a configuration audit event.

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