10.5Agent supervision

Who is supervised

Supervision applies to machine credentials only:

• API keys, used by scripts, n8n workflows and other integrations (Chapter 12, API keys; Chapter 14, n8n integration).
• Connected AI agents that signed in on a person's behalf over OAuth (Chapter 13, AI agents (MCP server)).

A person working in the console is never supervised. If a person lacks the authority for an operation, the request is refused on permissions; it is not queued.

Supervision applies only to commands that change a directory. Queries are never supervised, and neither are changes to the platform's own administration (users, roles, connections and settings).

The three supervision levels

Each API key and each connected agent has its own supervision level. The default, for new and existing credentials alike, is Guarded.

How the console describes the levels:

• Act without asking — "Runs everything it is allowed to, unasked. Changes to protected accounts and groups still wait for a person, and so do operations set to always ask agents."
• Ask before destructive and security changes — "Everyday work runs straight away — creating and editing accounts, resetting passwords, adding members. Deletions, and changes to permissions, delegations or policies, wait for a person."
• Ask before every change — "Every change waits for a person. Reading is never affected."

Supervision never widens what a credential can do. An agent can only ever perform operations its role permits; supervision decides only which of those permitted changes wait for a person first.

Unsupervised needs an approver

Choosing Act without asking pre-approves everything the credential will go on to do. For that reason:

• Only someone who holds operations:approve can set a credential to Unsupervised. The option is not offered to anyone else, and the server refuses it.
• The level lasts only as long as the acting person — the API key's owner, or the person who connected the agent — still holds operations:approve. If they lose that permission, the credential is treated as Guarded until they regain it.

Risk classes for agents

To decide what a Guarded agent may do unasked, every directory command has an agent risk class. It is related to the risk tiers on the Directory Policies screen, but not identical.

Two rules make the classes behave sensibly:

• Password resets and member additions are Routine, even though the Directory Policies screen lists them as Sensitive. They are the most common things an agent is asked to do, and a password-bearing command cannot be queued (see below), so classifying it otherwise would make a Guarded agent refuse it.
• An ordinary-looking update becomes Escalating if it writes a privileged attribute. The attributes treated this way are adminCount, managedBy, member, msDS-AllowedToActOnBehalfOfOtherIdentity, msDS-AllowedToDelegateTo, msDS-GroupMSAMembership, primaryGroupID, sIDHistory, servicePrincipalName and userAccountControl. An update to a user that sets a delegation flag in userAccountControl, for example, waits for a person at the Guarded level.

Safeguards that apply at every level

Three safeguards apply to every agent, including those set to Act without asking. They describe the change being made, not how far the agent is trusted in general.

Protected targets

A change waits for a person if any object it writes is protected. The platform checks every object the command touches — for "add X to group Y", both X and Y — and treats an object as protected when:

• it carries Active Directory's own adminCount=1 mark, which identifies members (current or former) of privileged groups such as Domain Admins;
• it sits inside a protected container configured on the directory connection, or the command would create or move something into one;
• for a deletion only, it is protected from accidental deletion.

Protected containers are configured per directory connection, in the connection's Protected containers list (see Chapter 5, Directory connections). A container covers its whole subtree, matched on a component boundary: protecting OU=Tier0,DC=corp,DC=local does not also protect OU=Tier0Lab,DC=corp,DC=local.

If the platform cannot read an object to check it, the object is treated as protected. Not knowing is a reason to ask.

Always ask agents

An operation pinned with Always ask agents — globally or for the directory in use — waits for a person whatever the agent's level.

An API key can be explicitly exempted from this pin with the option Skip the always-ask wait, intended for a reviewed workflow that runs unattended. The exemption waives the pin only: protected targets, the volume brake and the key's own supervision level still apply, and it never applies when the key is used by an agent over the MCP server. Setting it is described in Chapter 12, API keys.

The volume brake

Each request can look safe on its own while a runaway script deletes one object after another. The volume brake watches the rate instead. It counts the destructive operations each credential has carried out in the last hour. Once a credential reaches 20 destructive operations within that rolling hour, every directory change that credential asks for starts waiting for a person — not only its destructive commands — until the count drops again. Reading is not affected.

Details:

• The count is taken from the operations log, so restarting the service does not reset it.
• Only successful operations count; refused requests do not.
• A request that would take the credential past the threshold waits instead of running. A batch is counted by its destructive items before it runs, so a single 100-item batch cannot outrun the brake.
• Nothing is undone when the brake trips; changes already made remain.
• The approver sees the reason "This credential has made, or is asking to make, an unusual number of destructive changes recently, so it is waiting for a person until that settles."

When the brake trips, the platform sends the notification Agent Slowed Down once per trip. Its recipients are configured under Notifications (see Chapter 16, Notifications) and can be set per directory; the credential's owner is always copied, because they are the person who can say whether the integration is doing what they meant.

Server administrators can tune the brake in the configuration file under AgentSupervision:Volume: Enabled (default true), Threshold (default 20) and Window (default one hour).

Note: Unlike the other safeguards, the volume brake lets a request through if the count cannot be read. The other checks answer "is this change dangerous?", where uncertainty is a reason to ask; this one answers "has this credential been busy?", where uncertainty is not evidence of anything.

Commands that carry a password

A command that carries a password — for example a password reset or creating a user with an initial password — can never be queued, because the password would have to be stored until somebody decided. If such a command would otherwise wait for a person, it is refused instead, with HTTP status 403 and the error code Agent.ApprovalImpossible.

In practice this means:

• No agent can set the password of a protected account.
• A credential set to Ask before every change cannot reset passwords at all. The console says so beside the level: "Password resets are refused, not queued — a password cannot wait in an approval queue."

How the decision is made

For each directory command from an API key or agent, the platform checks, in this order:

1. 1Is any object the command writes protected (or unreadable)? If so, it waits — reason: protected target.
2. 2Is the operation pinned Always ask agents for this directory, and is the credential not exempt? If so, it waits — reason: pinned.
3. 3Has the volume brake tripped for this credential? If so, it waits — reason: volume.
4. 4Does the credential's supervision level cover a command of this risk? If so, it waits — reason: level.
5. 5Otherwise, the command runs.

If the answer is "wait" and the command carries a password, it is refused instead.

When a command waits, the caller receives HTTP status 202 Accepted with an operation handle, and the queued operation shows a plain-language reason for the approver and for the agent's user — for example "This agent asks before destructive and security changes." The queued row also names the API key or agent that asked, and summarises the impact (for example how many members a group has). Approving, rejecting and following up queued operations is covered in Chapter 9, Operations log, approvals and waiting operations.

A batch request is judged as a whole: it carries the highest risk of any of its items, any item's pin and every item's targets. If anything would wait, the whole batch waits as one operation.