# 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: ```sh 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`).