Agent registry

Most businesses discover their agent estate twice: once in a spreadsheet somebody assembles for an audit, and once in an incident. The spreadsheet lists the agents your team remembered; the incident involves the one they did not. That gap is structural rather than careless — an inventory maintained beside the runtime is updated by whoever remembers, while the runtime is updated by whoever ships, and the two diverge from the first week.

The questions an auditor actually asks are field-shaped. ISO/IEC 42001 A.4.2 asks for an AI system inventory. EU AI Act Art 26(1) asks that a system be used in accordance with its instructions, which requires a declared purpose to compare behaviour against. Art 26(2) asks that oversight be assigned to competent persons, which requires a named human per agent rather than a team alias. Each of those is answered by a field on the record — and each field is only worth having if it is the field the enforcement path reads, because a purpose nothing consults is a sentence in a document.

The second failure is quieter and shows up at review time. An access review that records agent X holds role Y certifies almost nothing, because role Y is editable and the review does not say what was in it. Six months later a named reviewer’s attestation sits beside a permission set they never saw, and nothing in the record distinguishes the two situations. Token Observe treats that as the defining problem of recertification rather than a detail of it.

Four fields are required — name, owner email, team and declared purpose — and 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, and it is 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, capped at 4,000 characters, and it is carried verbatim into every recertification snapshot.

Everything else on the record exists because some part of the request path reads it. That is the test the registry is designed around: a field that nothing consults is documentation, and documentation drifts.

A recertification is an append-only attestation by one named reviewer over one exact governance-bearing configuration. The snapshot covers name, owner, team, lifecycle status, role ids, the effective role grants, framework, tags, purpose, risk tier, budgets, rate limits, data policy, routing, the on-behalf-of requirement and metadata. Presentation-only description and storage timestamps are excluded, because a review invalidated by someone fixing a typo in a description trains reviewers to click through.

The part that does the work is the role grant. Each referenced role is bound by name, permission count and a SHA-256 over its normalised permissions — not merely by its stable identifier. That is what makes the attestation mean something six months later: editing a role changes the live digest immediately and marks every affected review stale, while the historical snapshot of what was actually attested is left untouched. Ordering is normalised where it grants no different authority — role ids, tags and permission actions are de-duplicated and sorted — so harmless reordering does not manufacture staleness and dilute the signal.

The write is guarded twice. The route refuses unless the submitted updatedAt and snapshot digest match what the server holds, and then the store re-derives the entire canonical snapshot inside the insert transaction and compares it again. On PostgreSQL that transaction takes a write lock on the agent row and a share lock on its roles; the share lock is not belt and braces, because a lock on the agent takes no lock at all on the roles table, and a role update committing in that window would be recorded as immutable evidence for a permission set that no longer exists.

Validity is 1 to 3,650 days through the API, and the console offers 30, 90, 180 or 365. A snapshot larger than 64 KB is refused with a message telling the operator to reduce governance metadata, rather than being silently truncated into evidence that omits part of what was reviewed.

Reading the registry needs viewer rank. Spend figures and recertification evidence are additionally gated on the reader’s team scopes, which are kept separate from their role for a specific reason: a viewer for Finance must not gain Engineering’s evidence merely because both are viewers. The scope check is applied at detail and export endpoints as well as at the list, because scoping the list alone leaves the detail URL as a way around the boundary.

The licensed ceiling on simultaneously active agents binds in exactly two places: creating an agent already in the active state, and the transition into active. Suspending, retiring, or editing an already-active agent is how an install that is over its ceiling gets back under it, so none of those is ever refused on licence grounds — a limit that blocked its own remedy would be an outage wearing a licence’s clothes. Draft, suspended and retired agents consume no capacity at all.

Entitlements never reach the governed request path. Being over a ceiling is reported, not retroactively enforced, which is also what makes a downgrade safe: an install that drops from 50 licensed agents to 10 keeps running all 50 and shows as over-ceiling, rather than silently losing 40 agents. And the ceiling is not a technical enforcement mechanism in the first place — deleting the licence file returns the install to an unlimited unlicensed fallback with every control still enforcing. What it produces is evidence: the source of the terms in force, the reason a licence was not used, a boot warning, and an audit row for every refusal. A true-up is argued from that record.