Register an agent

Steps

1. Go to https://agentauthority.org/owner.

2. Pick Personal or Company.

3. Create your account, pay, and pass the identity check.

4. Register the agent. Give it a name.

5. Download the registration request. Keep it private. It is a short-lived credential.

6. On the machine that holds the agent’s key, run:

   python -m registry.agent_connect --request registration-request.json --key YOUR_PRIVATE_AGENT_KEY_FILE

   If the key file does not exist, the command creates a new key there.

7. Back in the portal, review and accept the registration.

The private key stays on the agent’s machine. The registry gets only the public key and a signature.

TODO: how to install registry.agent_connect outside this repository.

Agent addresses: @username/agentname and @domain/agentname

Every agent has a public address that starts with @:

• A personal agent: @username/agentname, for example @jsmith/ralphie.
• A company agent: @domain/agentname, for example @coca-cola.com/ralphie.

A dot in the first part means a company domain. Usernames can’t contain dots, so the two never mix.

An address is only a pointer to the agent ID. The agent ID is the agent’s permanent identity. Signatures, records and the audit history always use the ID.

• Every agent needs a name. It must be unique among the owner’s agents.
• An agent can also have a display name. It is free text, and spaces are allowed.
• A personal address works only while the username is turned on. A company address works once the company’s domain is DNS-proven and the agent is registered. Otherwise people find the agent by its ID only.

Looking up an address

• Page: https://agentauthority.org/@jsmith/ralphie opens the agent’s public record. Without the @ (/jsmith/ralphie), you are sent to the @ form.
• API: GET /api/public/names/@jsmith/ralphie (the @ is optional) returns the same signed status as GET /api/public/agents/{agent_id}. The signed status always includes the permanent agent ID. It includes the @ address only while the address is visible.
• Lookup matches the exact name only. @jsm1th/ralphie does not find @jsmith/ralphie.
• Both return 404 when the address is not public.

When an address changes

An address changes when you rename an agent (POST /api/agents/{agent_id}/name), change your username, or transfer the agent to another owner. For example, @jsmith/ralphie can become @acme.com/ralphie.

• The agent ID, its history and its signatures stay the same.
• The old address redirects to the new one for 90 days. During that time only you, the original owner, can take the old name back.
• After 90 days the old address stops working, and anyone may claim it.
• If the new owner already has an agent with the same name, the agent has no name until the new owner renames it.

Your username

Only personal accounts have a username. A company’s names come from its proven domain.

• At signup you get a hidden placeholder username, like @u-7f3k2a90b1. It is never shown in public.
• Choosing a real username is optional. You can choose one when you register an agent, or later in Account & security.
• It is hidden from public pages unless you turn on “Show my username on public pages”. You can turn it off again.
• While your username is hidden or not chosen, public pages show the agent name, “Verified owner” and the agent ID.
• A username stays yours, even with no agents.
• To change it, use “Change username” in Account & security. Your old public addresses redirect for 90 days, and only you can take the old username back during that time.

Username rules

• 3 to 30 characters.
• Letters a-z (stored in lowercase), digits 0-9, single hyphens - or underscores _.
• No hyphen or underscore at the start or end, or two in a row.
• No dots. Dots are only for company domains, like acme.com/billing-bot.
• Lookalikes count as the same name. j0hn = john, and jane_smith = jane-smith = janesmith.
• Some words are reserved, like admin, support and verify.

Agent name rules

• 1 to 32 characters.
• Lowercase letters a-z, digits 0-9, hyphens - and underscores _. No spaces, dots or other symbols.
• Unique among your agents, ignoring case. Lookalikes are different names: ralph1e and ralphie can both exist.
• Some words are reserved, like admin and agent.

Companies

A company’s agents get addresses under the domain it proves with a DNS TXT record, like @acme.com/billing-bot. Company agent names follow the same agent name rules.

• A company can prove more domains on its Company page (“Add domain”). Every proven domain finds the same agents. @acme-robots.com/billing-bot redirects to @acme.com/billing-bot.
• Addresses use the company’s first domain while it is proven. If it lapses, they use another proven domain.
• Companies do not have a username. The exception is a trademark the company owns: once trademark checks go live, it will be able to claim the trademarked name as its username (for example dietcoke, addressed @dietcoke).