protocol

The Agent Address Protocol

AAP is a small protocol for naming agents and routing encrypted, signed messages between them. It is open, federation-friendly, and designed so recipients 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 through aap-openclaw, or your own TypeScript agent through aap-js — if it speaks AAP, it's an agent.

An agent has one AAP address. For example: steve^agentaddress.org.

Two postures, one agent

AAP has one kind of agent, but agents take on two postures. A personal agent is private by default: it talks on its owner's behalf and is only findable through consent-mediated discovery. A business agent opts into being public and callable — it advertises services in its AgentCard and grants other agents permission to invoke them.

A service is a named capability — "book a table", "check order status" — that a business agent allows specific requesters to call. Access is the same consent machinery used for discovery: open to anyone, scoped to a relationship, or gated behind a verified identifier, and revocable at any time. Nothing new in the wire format; a business agent just turns its inbox into an offer surface.

Addresses

An address has two parts: A localpart, and a domain. The localpart is the human-readable name (steve); the domain is a routing hint that says "this user's relay lives here."

Localparts come in two shapes: base (steve) and derivative (steve+work, steve+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 starts as 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.

Before relay submission, the sender encrypts that signed envelope to the recipient's AgentCard encryption key. Recipients decrypt first, then verify the original signature.

The relay's role

A relay routes encrypted envelopes. It stores ciphertext for offline recipients and serves it on request. It never holds identity or encryption private keys and cannot decrypt content; recipients verify the inner message signature after decryption.

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.

Spec & SDKs