How Agent Control Room supervises an agent

The two sides

The supervised application — the enforcement point — holds the data and runs the agent. Agent Control Room — the decision point — holds the rules and answers one step at a time. The separation is the point: the thing being governed is not the thing granting permission.

• Agent Control Room receives the workspace, agent, action, optional resource reference, a one-way payload fingerprint and any declared context facts needed to judge the step. Documents, prompts, generated content and other raw payloads remain in the supervised application.
• Every tenant workspace enters through its own address and its own key. A key bound to one workspace cannot be used on another workspace's entry point, and network rules can restrict where a call may come from.
• Refusal is the default. A tenant workspace with no saved rules refuses every request and says so.

Who may ask: the agent registry

A decision needs a subject. Every agent that acts in a workspace has a record here — a key, a name, an owner, and the actions it may ask for — and only a registered, active agent can be granted anything. The record is deliberately thin: it exists so rules have something to name and decisions have somebody to attribute, not to duplicate the inventory an organisation already keeps.

• Register from either side. An administrator can add an agent on the Agents page, and a calling platform can register one through the API as part of its deployment. Registering the same agent twice changes nothing.
• Nothing unregistered ever acts. An unknown agent's first request is refused with `agent_not_registered`, and the attempt is written down as waiting to be approved — so the registry can never quietly fall behind what is really calling.
• Your own CMDB stays authoritative. It can pull the registry and the wider ecosystem view through the API and reconcile them against its own inventory; models, versions and risk assessments belong there, not here.

One step, one request

Each governed step is a separate decideAction call. The caller names the registered agent and one declared action, supplies an optional resource reference, sends a fingerprint of the exact payload and includes a context object — empty when that action expects no facts.

• Three steps mean three requests. A permission for one action, payload or attempt never authorises another.
• The caller calculates each fact once and freezes the complete request for retries and any later approval claim. A changed payload or changed context is a different request and needs a fresh evaluation.
• The request identifier is derived from the complete request, including context. Settled answers can then be replayed safely for 24 hours if a response is lost, while a waiting answer is never frozen in front of a later approval claim.

How the action key is matched

The action is the centre of every decision: it is the word the caller uses for what it is about to do, and it is what the rules are written against. The caller sends it as a plain string; nothing about it is guessed here.

• The workspace declares its own actions. Each one has a key the caller sends (for example `document.read`), a plain-language label, an optional description, a payload-binding note and, where needed, a context contract.
• An integrator reads that list rather than being told it. describePolicyEngine returns exactly the actions this workspace has declared, so the calling side can align its own vocabulary before it sends anything.
• Matching is by exact string. A rule's “Action is one of” condition holds when the key sent equals one of the keys ticked. `document.read` and `document.Read` are different actions, and a near-miss simply fails to match.
• An undeclared key is refused. If the workspace has not declared the action, the request is refused whatever the default effect says — an unknown word can never fall through to an allow.
• A declared key with no matching rule still falls to the default. Declaring an action does not permit it; it only makes it something rules may be written about.
• Three things must line up for a new action to work end to end: the workspace declares it, the applicable rules or default permit it, and the registered agent is allowed to ask for it.
• Retiring an action removes it from new authoring choices. It does not erase existing rules or revoke decisions already made.

The two catalogues

The catalogues are optional starting points. They help an administrator name actions and useful business facts consistently, but the workspace remains in control of what it adopts and enforces.

• The public action catalogue shows the grouped suggestions and their guidance. Importing an action creates an editable workspace copy; it does not grant permission, change agent permissions or add a new step to the calling application.
• The condition catalogue suggests facts, meanings, agreed values and likely suppliers. Adopting a suggestion neither requires nor enforces the fact and never creates a rule or chooses Allow.
• Only the workspace's adopted actions, context contracts and rules form its working configuration. Later catalogue changes never overwrite local edits.
• An existing broad Allow rule or Allow default may already cover a newly declared action. The import review identifies those possible paths so the administrator can judge them before saving.

Context is checked before rules

A context contract describes the facts a workspace expects for one action. It may be published as guidance first and enforced only after the caller is ready. When enforced, it checks whether the request is complete and well formed before any policy rule runs.

• Facts use literal, top-level field names. They can be agreed values, unrestricted text, true or false, or numbers with minimums, maximums, inclusive boundaries, units and whole-number checks.
• Required means required when the contract is enforced. Optional facts are checked when supplied, and undeclared extra facts are accepted.
• A missing, wrong-type, unlisted or out-of-range fact produces Not decided. No rule ran, no person was asked and no permission was issued; this is not a fourth policy outcome.
• A valid context does not grant anything. It only means the request contains enough valid information for the rules to judge it.
• Facts must come from trusted application code or verified services, not from a model choosing the answer that will permit itself.
• A fact can be asked to carry its provenance: who asserted it and when it was observed. The workspace can name the services whose word it accepts and how recent the observation must be, and the caller then sends the value together with that assertion instead of a bare value.
• An assertion that is missing, comes from a service the workspace never named, or was observed too long ago produces Not decided, exactly like any other incomplete context. Freshness is measured against the moment the decision is made, so a safely replayed answer stays the answer it was.

Rules produce one of three outcomes

After the agent, action and any enforced context contract have passed their checks, the ordered rules answer the request. The first matching rule wins; if none matches, the workspace default answers.

• Allow (`grant`) — a signed, single-use decision, normally valid for five minutes and bound to the exact payload fingerprint.
• Refuse (`reject`) — the step must not happen. The rule or default and its reason are recorded.
• Ask a person first (`pending`) — no permission is issued. An approval request appears in the workspace queue and its reference is returned to the caller.
• A rule that has reached its own limit on how often it may grant answers Refuse, naming the limit and the time the next slot opens. It is a policy judgement, so it is recorded as a refusal, not as Not decided.
• All conditions within one rule must match. An “Action is one of” list means any one of those action keys can satisfy that condition; it does not approve several actions together.

The approval gate, step by step

A rule that says 'Ask a person first' produces this sequence.

• Waiting for a person — the request is open for up to seven days. Nothing is granted and the application must not perform the step. Repeating the same waiting request reuses the open approval instead of filling the queue.
• A workspace administrator approves or refuses on the Approvals page. The queue shows the policy and rule that held the step and, where the rule requires it, the administrator must write a note.
• Where the rule asks for separation of duties, the agent's registered owner cannot approve its steps: the queue says so and the engine refuses the attempt as well, so the screen is never the only safeguard. Anyone may still refuse.
• Waiting for approval claim — approval does not push permission to the caller. It opens a fifteen-minute claim window for exactly the same agent, action, payload fingerprint and frozen context.
• The caller polls getApprovalStatus. When it reports that the approval is granted and claimable, the caller repeats the byte-identical decideAction request to claim it.
• Approval claimed — Agent Control Room issues the resulting signed grant, normally valid for five minutes, and marks the approval consumed. Safe retries with the same request identifier return that same grant rather than spending a second approval.
• If nobody answers within seven days, the approval request expires. If a person approves but the caller does not claim within fifteen minutes, the approval claim expires. Agent Control Room never opens a replacement request automatically; the calling application may offer a deliberate Ask again action.
• Refused and expired approvals never become permission. Throughout every waiting, refused or expired state, the supervised step remains blocked.

Flow

agent step ──▶ decideAction ──▶ Agent Control Room
                          │
       not decided ◀──────┤  context incomplete (no rule runs)
                          │
         allow ◀──────────┼──────────▶ refuse  (step does not happen)
                          ▼
                   ask a person first
                          │
              approvals queue in this workspace
                          │  administrator approves
                          ▼
             15-minute claim window
                          │  next identical ask
                          ▼
             allow (single use, normally 5 min)

What the policy engine expects of a supervised application

• Three steps means three asks — a decision is never reused for another step, another attempt or another payload.
• A retry after an approval re-asks for the same step with the same fingerprint. Earlier steps being re-asked in the same run is normal and expected; the record is meant to show every ask.
• A changed payload is a different request. If the document or the model output changed, the fingerprint changes, and any earlier approval no longer applies.
• No answer, or an answer that cannot be verified, is a refusal. Nothing acts on a doubtful decision.
• Approvals are administered here and nowhere else. A supervised application has no approve, refuse or revoke surface of its own.
• The caller must ask about every governed action it performs. Declaring an action in Agent Control Room does not insert that check into external application code.

How a rule is written

A rule is a named intent inside a policy, a list of conditions that must all hold, and what to answer when they do.

• Conditions can check the agent, action, resource reference, a field the caller sent, a numeric comparison, a time-of-day window, a day of the week and the caller's network.
• A numeric range in a context contract asks whether a number is valid input. A numeric comparison in a rule asks what permission follows — for example, allow fewer than 15 pages but ask a person for 15 or more.
• Every decision is a pure function of the request in front of it and the workspace's saved rules — the same question, asked twice, is answered the same way. The control plane around it deliberately remembers: decisions, approvals, claims and safe replays are all kept. Agent Control Room is not stateless; it is deterministic and replayable.
• How often a rule may grant is the one counted control. A rule can say “at most five grants an hour” and “not again within a minute”, counted per agent and action, and only issued grants count. Cumulative spend, quota ledgers and other business totals remain outside the engine.
• A rule that asks for a person may also require that the agent's registered owner is not the person who approves it.
• Each tenant workspace declares the actions its agents may ask about, on the Policies page: a key the caller sends, a plain-language label, an optional description, and what a decision's payload hash binds for that action. An action the workspace has not declared is refused, whatever the default effect says.
• That declared list is what describePolicyEngine returns, so an integrator reads the workspace's own contract rather than a list shipped with the product.
• Rules written before conditions existed keep working unchanged: their agent, action and resource prefix are read as exactly those three conditions.
• A rule may also say how long its grant stays usable and, when it asks for a person, that the approver must give a reason.
• Policies themselves are named things with a purpose, an owner, an order and an on/off switch. Rules are evaluated policy by policy in that order; turning a policy off skips its rules, and removing a policy leaves its rules in force under Uncategorised rather than switching controls off by accident.
• Before saving, the editor shows what the new rule set would have answered for the decisions this workspace actually made.
• Through the API, replacing rules without sending actions preserves the workspace's action vocabulary and context contracts. Sending actions means deliberately replacing the complete action list.

How Decisions explains what happened

Decisions keeps the answer and the evidence needed to understand it without exposing the underlying document, prompt or generated content.

• Not decided means a pre-rule check could not validate the request. Refused means a rule or the workspace default did evaluate it and denied the step.
• For context failures, authorized administrators can compare each declared expectation with the value the caller submitted, including missing, wrong-type, unlisted and out-of-range facts.
• The original policy reason remains historical: it explains why the first request was held. The linked approval status can continue from Waiting for a person to Waiting for approval claim, Approval claimed, refusal or expiry without rewriting that history.
• Approval details preserve who answered, when, the approver's note, the claim deadline, whether the caller claimed, and the resulting Granted decision.
• Older records may not contain every evidence snapshot. An unavailable historical comparison is not proof that a fact was missing.

What is kept here

• Each workspace's versioned rules, adopted action vocabulary and context contracts, isolated from every other workspace.
• Every decision: agent, action, resource reference, fingerprint, effect, rule and policy, rule-set version, context evidence, issue and expiry time.
• Every approval: who asked, what for, which policy and rule held it, who answered, when, with what note, its deadlines, and whether the resulting permission was claimed.
• The workspace audit trail, including requests, approval checks and claims, refusals, rule changes and safe replays.

Stopping everything

The pause switch on the Policies page holds every agent in the workspace at its next step: the next ask is simply refused, nothing is reconfigured and nothing is lost. Resuming puts the workspace back exactly as it was. Individual rules can also refuse one agent or one action without pausing the rest.