How to Register an AI Agent, and the One Field to Decide Before You Start
Decide custody first, because the default decides for you
The creation route defaults custody to managed. Omit the field and you get managed custody.
Managed means we generate the agent's signing key, encrypt it and keep it. There is an export route, and exporting returns the key without deleting our copy.
To hold your own key, send custody: "byo" and a publicKey, sixty-four hexadecimal characters.
The schema will reject anything else, and the flow is two calls instead of one.
Neither choice is wrong. Defaulting into one without knowing is.
Step one: be an operator with a verification reference attached
Creation refuses an operator with no reference. The failure carries its own problem type and tells you where to obtain one.
A reference that exists but was not confirmed is a different failure with a different message, on purpose, because the two need different fixes.
The identity check happens on another surface. This one ingests the reference and never runs a check itself.
Step two: create the agent
Send the creation request with an operator credential. The body accepts four fields and no others: the custody choice, a public key when the custody is your own, a capability list of up to sixty-four strings, and an optional card address.
Managed custody returns a created agent with an identifier already on our chain.
Your own custody returns the agent staged and awaiting your signature, together with a signing block carrying a nonce and the network name. The agent is not usable yet.
Step three, for your own custody only: sign and submit
Build the identifier-creation transaction with the key whose public half you registered, sign it, and submit it to the agent's identifier route.
The chain enforces that the signer matches the registered key, so a mismatch fails there rather than being accepted and discovered later.
Those keys never enter our escrow, which the export route states by name when it refuses them.
Step four: the passport is asynchronous, so do not wait on the response
Creation enqueues the registry anchor and returns. The passport is minted afterwards by a background job.
A guide that showed a token in the creation response would be describing a system nobody built.
Step five: the card is public
The agent's card needs no authentication. It is what the passport's address points at, and it carries types, timestamps, credential identifiers and status references, with no claim data of any kind.
Capabilities are free strings, and there is no vocabulary
Measured: nothing anywhere defines an allowed set. A capability is any string of up to two hundred and fifty-six characters, and you may send up to sixty-four of them.
CONTROL: the same routes file declares eight enumerated vocabularies for other fields, so this codebase uses an enumeration where somebody wanted a controlled set. Capabilities are not one, and that is a decision rather than an omission.
The interface is honest about it, describing the field as a custom capability and offering a shape rather than a menu.
The consequence belongs on a how-to page, because it is the caller's problem. A verifier checking that an agent holds a required capability is doing string equality against a vocabulary nobody agreed on. Two operators can mean different things by the same word, and the same thing by two different words, and nothing in the system will notice either.
If you are issuing capabilities that somebody else will check, agree the strings out of band and write them down.
What the route contract gets right
The schemas are strict. Identifiers must be well-formed, the public key must match its exact shape, list sizes are capped, and unknown fields do not silently pass.
The free-tier check runs twice on purpose: a cheap early rejection, and an authoritative, race-safe reservation inside the insert transaction. Somebody thought about two requests arriving at once.
And the public card requires no account, which is what makes anything about this checkable by an outsider at all.