Agent onboarding

Four fields are required to create an agent record: a name, an owner email, a team and a declared purpose. The last two are the ones worth arguing about in the meeting. The owner email is the human accountable for a thing that is not a human, lower-cased on write so accountability does not fork on capitalisation. The declared purpose is the field a regulator asks for; it is required rather than optional and it is carried verbatim into every later review, which means a purpose written as does support things will be attested by a named reviewer six months from now and will not help either of you.

Everything else is declared rather than mandatory, and each field earns its place by being read somewhere in the request path. A risk tier, defaulting to limited. Team and tags, which policy scope and kill switches match on — team case-insensitively, tags case-sensitively. A data policy expressed as three independent settings rather than one flag. A routing ceiling, which caps the tier an agent may reach rather than targeting one, so a cheap classifier cannot quietly cost frontier prices. A per-agent switch requiring a named human on every call, off by default. And free-form metadata, which is where an assessment reference belongs so it travels into the review record rather than living only in a console.

The record starts in draft, which is deliberate: a record can exist before anyone has decided to run it. Role references are validated against the authoritative rows inside the writing transaction and an unresolvable one is refused by name, because a dangling role would otherwise reduce the agent to deny-by-default silently — which reads as a policy decision rather than as a typo.

One thing to check on any implementation before you rely on it: whether the record you just created is the record the enforcement point reads on every call, or an inventory maintained beside the runtime. The second kind is updated by whoever remembers while the runtime is updated by whoever ships, and the two diverge from the first week.

Write the grants as an allowlist of actions the declared purpose requires, and expect the exercise to surface grants nobody can justify — that is the exercise working. Deny by default means an action no permission names is refused and an agent with no roles can do nothing, so the failure mode of getting this wrong is a refusal rather than a silent permission.

Then set ceilings, and set them before you write a single policy, because a runaway loop does not require anybody to misbehave. Four in money — per request, rolling hour, day and month — and three in rate, on requests, tool calls and tokens per minute. The hourly window is the one that catches a loop in minutes rather than at the daily boundary.

One check belongs here specifically and it is the one most likely to be missing: confirm that a model with no price row fails closed for this agent rather than being estimated at zero. A zero estimate passes every ceiling above it, an unmetered estate and an idle one look identical on every spend surface, and the customer finds out from the vendor invoice. Token Observe refuses before egress with a typed error naming the unpriced model, the provider that would have served it and how many further fallbacks are also unpriced — for any agent with a ceiling configured. An agent with no ceiling is explicitly unbudgeted and is unaffected, which is why the count of agents with no ceiling is a number worth watching.

Only now write policy, and stage every rule. Observation mode evaluates the rule exactly as enforcement would, records the match on the trace with the policy, its action and why it matched, then skips it. Let it run against real traffic — a day is better than an hour — then look at what it matched and ask the only question that matters: if this had been enforcing, would the blocked request have been wrong to allow. Promote one rule at a time, and start with the one blocking credentials in prompts, because a leaked credential cannot be un-leaked and, unlike personal data, there is no legitimate reason for one to appear in a prompt at all.

Three things get decided once during onboarding and then have to be maintained, and skipping them is how a governed agent quietly becomes an ungoverned one that is still in the registry.

A review cadence with a named owner. A recertification binds a named reviewer to a digest over the exact governance-bearing configuration — including a hash over each referenced role’s normalised permissions rather than merely its identifier, so widening a role marks every affected review stale immediately without rewriting what was attested. The honest limit belongs beside it: an overdue or stale review never suspends the agent, and there is no notification scheduler, so the cadence is a process you run rather than one the software runs for you.

A retention period somebody chose. The default is unset, and unset means keep forever, which over-satisfies a minimum-retention duty and satisfies no storage-limitation duty at all. Decide the period, and then write down what it does not cover — approvals, discovery findings, webhook delivery records and identity snapshots each sit outside it — before anybody quotes a number to a data protection officer.

The evidence-integrity settings, switched on while the history is short. Keying the audit digests requires a key injected from a secret manager your database administrators cannot read and a two-boot ceremony; anchoring requires a signing key held in a key management service and a destination somebody else controls. Both cover only what comes after them, and there is one consequence worth planning for rather than discovering: reviews recorded before the first keyed checkpoint become invalid and have to be repeated, because promoting a legacy record without verifying its descendant path would let a database writer rewrite both the record and the thing referencing it.

Finally, decide the operational answers before traffic rather than during an incident: who may engage and release the kill switch, who owns the backup, who has authority to restore, and what happens to agent traffic while the gateway is unavailable. A control that refuses when it cannot decide is a dependency of everything behind it, and that sentence is much easier to agree with in a design review than at three in the morning.