--- title: "Capability: Agent registry" canonical_url: "https://tokenobserve.com/platform/agent-registry" published: 2026-09-02 last_updated: 2026-10-21 --- # Capability: Agent registry One record per agent, and it is the record the gateway enforces against. ## What it is The agent registry is Token Observe’s system of record for every AI agent you run: an id, a named human owner, a team, a declared purpose, a risk tier, budgets and rate limits, in one row. It is the same row the gateway reads on every call, so the inventory cannot drift from what is running: step 2 resolves this record, and step 6 refuses the request whenever the status is anything but active. Recertification sits on top: a named reviewer attests a SHA-256 digest of the configuration in front of them, and because that digest covers each role’s normalised permissions rather than its id, editing a role makes every affected review stale. ## Facts - Required at creation: Name, owner email, team, declared purpose - Lifecycle states: draft, active, suspended, retired - Credential storage: SHA-256 only; the token is shown exactly once - Recertification posture: never, current, due, overdue, stale, invalid ## The limit What it will not do: An overdue review never suspends the agent itself ## Why it exists: An inventory nobody enforces against is a spreadsheet. Most businesses discover their agent estate twice: once in a spreadsheet somebody assembles for an audit, and once in an incident. The gap is structural: an inventory kept beside the runtime is updated by whoever remembers, and the runtime by whoever ships. The questions an auditor asks are field-shaped. ISO/IEC 42001 A.4.2 wants an AI system inventory; EU AI Act Art 26(1) wants a declared purpose to compare behaviour against, and Art 26(2) wants oversight assigned to a named person. Each is a field on the record, and a field is only worth having if the enforcement path reads it. ## How it works - Register the record: POST /api/agents with name, owner email, team and declared purpose. Status defaults to draft, so a record can exist before anyone decides to run it. Role ids are validated inside the writing transaction, because a dangling id would silently reduce the agent to deny-by-default. - Issue a credential, once: The create-key response carries the only copy of the plaintext that will ever exist; only its SHA-256 and a display prefix are stored. Minting is admin-only, because it hands out gateway authority. Revoking is one write. - The gateway resolves this record, not a copy: Step 2 loads the agent, its roles, the engaged kill switches and its spend window. Step 6 reads them in a fixed order: kill switches, lifecycle, RBAC, budget and rate ceilings, then the policies scoped to this subject. - Recertify against an exact configuration: An operator submits the digest they inspected. The store re-derives the canonical snapshot inside the insert transaction and compares again, so a concurrent edit returns a typed 409 rather than certifying configuration nobody read. ## Where it runs in the request path Step 2 of the request path ## What it does not do - Token Observe does not discover your agents. Registering one is a deliberate act by a named person; anything calling a model without a record here is the shadow-AI radar’s problem. - There is no recertification notification scheduler, and an overdue agent is never suspended automatically. That needs a per-install grace period, an escalation owner and a dry-run path first. - A recertification is not a signature. It is a hash record bound to a keyed audit entry, so on an install with no audit HMAC key configured it evidences internal consistency and nothing about a determined database writer. - The licensed agent ceiling is not enforcement. Deleting the licence file returns the install to an unlimited fallback with every control still running; the ceiling produces an audited record of an install operating past its terms. - Risk tier is recorded and reviewed but is not a policy-scope dimension. Policies match on agent id, team and tag, so a rule intended for high-risk agents is written against a tag you maintain. - The audit diff names fourteen fields. A change to routing or to the on-behalf-of requirement is audited as an edit but is not named in that list; the recertification digest, which does cover both, is what catches it. ## Read next - https://tokenobserve.com/platform/agent-permissions - https://tokenobserve.com/platform/spend-controls - https://tokenobserve.com/platform/audit-chain ## Questions and answers Q: What happens to a running agent when someone edits its record? A: The change applies to that agent’s next governed request. There is no redeployment and no propagation step, because the gateway resolves the record at step 2 rather than from an exported copy. A suspension bites on the next call, refused with a typed 403 naming the lifecycle state and published as an agent.suspended event. Q: Does an expired recertification stop the agent? A: No, by design. Token Observe exposes the posture (never, current, due, overdue, stale or invalid) but runs no notification scheduler and does not auto-suspend. Automatic suspension turns a compliance calendar into an availability control, which needs a grace period, an escalation owner and a dry-run path rather than a surprising default. Q: Why does editing a role make an agent’s review stale? A: Because the review attests what the agent could do, not which identifiers it referenced. The snapshot binds each role’s name, permission count and a digest of its normalised permissions, so widening a role marks every agent referencing it stale. Binding role ids alone would let a reviewer’s name sit beside a permission set they never saw. The long-form detail on this capability (the anchored sections, the worked policies and the error envelopes) is on the page itself at https://tokenobserve.com/platform/agent-registry.