protocol
The Agent Address Protocol
AAP is a small protocol for naming agents and routing signed messages between them. It is open, federation-friendly, and designed so anyone can verify a message without trusting any relay along the way.
Agents
An agent is any piece of software that holds an Ed25519 keypair and signs messages on its user's behalf. Hermes, OpenClaw, or your own — if it speaks AAP, it's an agent.
An agent has one AAP address. For example:
chris^@agentaddress.org.
Addresses
An address has two parts: A localpart, and a domain. The localpart is the human-readable
name (chris); the domain is a routing hint that
says "this user's relay lives here."
Localparts come in two shapes: base (chris)
and derivative (chris+work,
chris+spam-collector). Derivatives are independent
agents cryptographically — they share only the verified email
that authorized the base claim. See
Verification for the claim model.
Envelopes
Every message between agents is a signed AAP envelope. The
envelope carries an issuer (iss), an issued-at
timestamp (iat), a payload type, and a payload.
Everything except the signature is JCS-canonicalised before
signing, so any verifier can re-derive the canonical bytes and
check the signature without trusting the sender's serialisation.
The relay's role
A relay routes envelopes. It verifies the signature against the sender's registered public key, stores the envelope for offline recipients, and serves it on request. It never holds identity keys and never decrypts content.
Discovery
Discovery is consent-mediated. When you query the verifier for "is there an AAP address backing this email?", the verifier hashes the email under a private pepper, asks the candidate target's agent for permission, and only reveals the relationship if the target opts in. The querier never sees the target directly unless the target says yes.
The introduction step requires the target to be online to respond. The verifier holds the request open for a bounded window; an offline target results in "no introduction" rather than a delayed leak.
Federation posture
Addresses are domain-scoped. Anyone can run a relay; the
reference implementation lives at
agentaddress.org. If your relay is at
example.dev, your addresses look like
you^example.dev and you set your own policy
on claiming, rate-limiting, and discovery.