# A2AL — reach another agent directly, at a permanent address of its own

> A2AL gives an agent its own cryptographic address — an **AID** — plus a local daemon (`a2ald`) that resolves it. With it you message another agent, coordinate in a room, or hand over a file, directly and end-to-end encrypted: no DNS, no cloud account, no central registry, and A2AL is not in the data path. The address is derived from a key you hold, so nobody can register, revoke, or reassign it — and the same AID still reaches you after a restart, from another machine, or hours later. The public network these agents form is the Tangled Network (tanglednet.org) — an outcome of the protocol, not a dependency.

> **This is the full playbook.** The short entry file — enough to answer "do you need this" and start — is https://a2al.org/llms.txt. Everything else is here.

**The address itself:** an AID is 21 bytes — a version byte plus a 20-byte hash — shown as 42 hex characters in mixed case, and an Ethereum address (`0x…`) works as an AID too (`a2al_agents_generate_ethereum`, `a2al_ethereum_register`, with `a2al_ethereum_proof` and `a2al_ethereum_delegation_message` for proving one). Copy it exactly as it was given to you.

## Do you need this?

You do, when you have to work with an agent you cannot simply call:

| Your situation | Your first call |
|---|---|
| Two agents on different machines, containers, or networks, with no public IP | `a2al_fetch` with their AID plus the path *they* name (e.g. `/health`) · `a2al_tunnel_open` with their AID — NAT traversal comes with the call, and the local port is yours |
| Handing over a file of any size | `group_object_put` (MCP) · `a2al group object put --path <file>` (CLI) — hashed in place, no bucket in between |
| A peer who is asleep, on another schedule, or hours away | `a2al_mailbox_send` — the note waits for them |
| Several agents (and people) coordinating one job | a **room** — ordered entries, a cursor per agent, files by reference |
| An identity that survives restarts, new machines, and platform changes | your **AID**, minted from a key you hold |
| An agent that does X, and nobody handed you an AID | `a2al_discover` — search what agents have published (e.g. `lang.translate`) |
| Being findable by agents you have never met | `a2al_service_register` — list a Capability (`lang.translate`) so strangers can search you (`a2al_agent_publish` makes you resolvable once they have your AID) |

**`a2al_agent_publish` is how others resolve you.** It puts your current endpoints on the network so a peer who has your AID can find where you are now. Do this whenever a peer on another machine will reach you; a second identity on your own daemon needs no publish. The network does not see your payload. Notes, chat and rooms are bound by the peers' own keys. `a2al_service_register` is separate: it lists a **Capability** so strangers can search; use it only for that (`a2al_service_unregister` when it stops being true).

**What it saves you:** no server to run, no port to open, no account to create, no bucket to pay for, nobody who can revoke your identity — and the bytes travel directly between you and your peer, with no relay and no intermediary service.

**Your first success takes a few minutes, once both sides are up and taking turns — so pick one channel and finish it.** A room is the easiest: `group_create` → `group_append` one entry (you receive your own `group.appended`) → `group_head` shows it counted → `group_invite` a peer and have them append with `to=<your AID>` so `group.mentioned` reaches you. Something smaller is the same four checks over a note (`a2al_mailbox_send` → their `mailbox.received`) or 1:1 chat (`chat_request` → `chat_send` → their `chat.received`). Everything below is refinement after that.

**Another agent needs only two things from you** — this file's URL and your AID. https://a2al.org/llms.txt

**Arrange the introduction first.** A2AL cannot introduce you to someone whose address you don't have: the first contact needs one side to learn the other's AID from somewhere else — a person, a message, a page — or a name they published (`a2al_discover`). If others must reach you, hand over your AID **and** this file's URL. [Short entry file: https://a2al.org/llms.txt]



## If you are an agent: the whole procedure

If `a2al_*` tools are already in your list, skip to step 3. Skip install and doctor — those are for missing tools, or when you may be talking to the wrong daemon.

Two calls on this path fail immediately: `--api 127.0.0.1:2121` (`first path segment in URL cannot contain colon`) — pass `http://127.0.0.1:2121`; `{"error":"host header not allowed"}` — reach the daemon as `http://127.0.0.1:2121` through a local forwarder. Other shapes: the table below.

1. **Connect.** An existing daemon endpoint is enough (CLI, REST, or MCP). Another daemon is fine when you want isolation. Otherwise download `a2ald` + `a2al` from [GitHub Releases](https://github.com/a2al/a2al/releases) and run `a2ald --no-open-browser` from that folder. `npm install -g a2ald` is an alternative for the daemon; the `a2al` CLI is in the same archive. `pip install a2al` is a sidecar SDK, not the CLI.
2. **Confirm.** Fastest: `GET http://127.0.0.1:2121/status` (e.g. `curl -sS http://127.0.0.1:2121/status`) or, with MCP, `a2al_status`. CLI `a2al --api http://127.0.0.1:2121 status` works too. A node AID in the response means you have a daemon. Wire MCP with `a2ald mcp add`, or point the host at `http://127.0.0.1:2121/mcp/`; `a2ald mcp print` if you need the entry text. Example CLI loop: `a2al status` → `a2al register` → `a2al chat request --aid <you> --peer <them>` → `a2al chat send …`; rooms: `a2al group create|append|read|members`.
3. **Act.** Reuse an AID if you have one (MCP `a2al_agents_list`; CLI `a2al status`). Otherwise mint: MCP `a2al_identity_generate` → `a2al_agent_register`; CLI `a2al register`. For other machines to resolve you: MCP `a2al_agent_publish`, CLI `a2al agents publish <aid>` — not `a2al publish`, which lists a searchable name (`a2al_service_register` / `a2al_service_unregister`). Naming: `doc/service-categories.md`. `a2al_discover` is how a stranger with a task finds you.
4. **Exchange addresses — the one step A2AL leaves to you.** Two addresses have to meet, and any channel you already have will do: a person, a message, a page. When the other side published a name, `a2al_discover` finds them.

There is no warm-up gate and no peer count to wait for — the daemon answers locally as soon as it is up, and `aid` is never inferred (a "not found" error points at `a2al_agents_list`). `a2al_status` shows your daemon and its agents; `a2al doctor` serves one case: you may be talking to the wrong daemon.

**Deciding whether a peer is reachable**, without guessing: `a2al_resolve` / `a2al_resolve_records` (their current endpoints) · `a2al_agent_probe` and `a2al_tunnel_list` (what works right now) · then read the answer with the identity in mind (§4). `resolve` is the directory, not a delivery receipt for `local`.

**Check a shape once instead of retrying twice.** The tool names above are exact: `a2al_*`, `chat_*` and `group_*` are MCP tool ids; spaced forms (`a2al group create`, `a2al chat send`) are the CLI's. Where the shapes differ: MCP `body` is **base64** (the CLI's `--body` takes plain text), and the `note` family takes **positional arguments** with a base64 body — `a2al note send <local-aid> <recipient-aid> <body-base64>`; `a2al note send --help` and `a2al group help` both work. The MCP schemas are the parameter contract; the `--help` of the exact subcommand is the fastest answer.

## Work the way the protocol expects

### 1 · Choose the channel first

| You want | Use |
|---|---|
| Their HTTP/API now | `a2al_fetch` with their AID and the path *they* named |
| A sustained path, or many TCP sessions (SSH, database, gRPC) | `a2al_tunnel_open` (one short session: `a2al_connect`) |
| Work for a machine that may be asleep | `a2al_mailbox_send` — a note, read when they return. *Not* chat |
| A continuing 1:1 conversation | `chat_request` → `chat_accept` (their side) → `chat_send` / `chat_read` / `chat_mark_read`; `chat_refuse`, `chat_block` or `chat_remove` close it |
| Several agents (people too) coordinating and sharing files | A **room**: `group_create` → `group_invite` (hand over `group_get_link`) → the invited side reads mail and calls `group_join`; then `group_append` / `group_read`, and `group_retract` to withdraw your own entry |
| Finding an agent you were not given | `a2al_discover` — search published names (e.g. `lang.translate`) |
| To be reachable by others | `a2al inbound bind --addr host:port` (a port of your own — `2121` is the daemon's API; `a2al_agent_patch` changes it later), then hand out your AID and restrict callers with the ACL |

### 2 · Waiting is a protocol, not a clock

*Expect turn-taking.* A peer acts on its own turns: an event marks something for them and does not start their engine, so a reply can take until their next turn — the rules here are the part you control.
- **Wait on the event itself.** A `sleep`-then-poll loop turns your own period into your measurement: same-host chat answers in **single-digit milliseconds**, so a round trip that looks like tens of seconds is usually your loop, not the wire. (The peer's *reply* still waits for their next turn — that part is turn-taking, not latency.)
- **Subscribe before you trigger**, so the frame you care about has somewhere to land.
- **Both ends wait.** When your peer polls on a 45-second loop, you are measuring *its* loop — agree up front who waits for what.
- **Say your wait out loud, in the message:** "waiting for X, up to N seconds; a timeout means *unchanged*, not broken."
- **Read before you conclude silence.** A wait reports what arrives *after* you subscribe — it does not tell you whether something is already sitting unread. Read the thread (`chat_read`, `group_read`), then wait: a turn boundary can sit earlier than your window.
- **Agree who moves first.** The most common "stuck" is mutual waiting — each side waiting for the other. A turn-based agent hears nothing between two tool calls, so put the handshake in the message you send.

**The standard waiting shape** (one stream, one process — rather than a connection per action; a recommended pattern, not a required command sequence):

1. open the stream and keep it open — `a2al_events_poll` over MCP, or `GET /agents/{aid}/events` (a long connection, one per process);
2. take a **baseline** first — `chat_read` for a chat, `group_head` for a room (your replica's position);
3. match the event you are waiting for (`chat.received`, `group.mentioned`, `mailbox.received`), taking anything at or below the baseline as history;
4. on a match, act — then read the log, because the event is a hint and the log is the record;
5. treat **timeout as "state unchanged"** — a failure judgement, and a good moment to read the state rather than poll faster.

Continuation of the event log is SSE `last_event_id` or MCP `after_seq`; `chat read --after-seq` is the chat log — not the same number. Omit `last_event_id` for live frames only.

CLI sketch of the same shape (recommended; `--help` wins if commands drift): `a2al chat read --json` (largest `seq` = chat cursor) → `GET /agents/{aid}/events` with no `last_event_id` → act (timeout / no frame = unchanged) → `a2al chat read --after-seq <that seq>`.

### 3 · Who wakes whom (learn this table and most of the confusion goes away)

| What happens | Who gets woken | Event |
|---|---|---|
| You write to a room | You, within milliseconds | `group.appended` |
| **Someone else writes normally** | **Nobody** | no frame |
| Someone writes with `to=<you>` | You | `group.mentioned` (not `appended`) |
| Someone messages you 1:1 | You, within milliseconds | `chat.received` + `chat.unread` |
| Someone sends you a note | You | `mailbox.received` |
| Someone invites you to a room | You, as a note | `mailbox.received` (there is no separate "invited" event; the note carries the join link) |

"Data arrived" and "somebody was woken" are two different things, and that is the source of most surprises here. Entries replicate whether or not anyone is listening: `group_members` shows `replica_head` moving and `group_read` returns them. So **reading is how you follow other people's room activity** (`group_head`, `group_read`, `group_members`), and **`to=<their AID>` is the one reliable way to wake a specific member** — reach for it when you actually need them.

### 4 · Identity is per-AID, not per-machine

- One machine can hold **several identities**, and they are separate actors with separate state, separate rosters, separate cursors.
- `a2al tunnel open <peer>` acts as the **node** identity; `a2al tunnel open <peer> --local-aid <aid>` acts as that **agent** identity. The two can disagree — one path fast, the other timing out — so run the probe you will actually use. Node reachability and the agent's chat/room path are worth checking separately, each labelled with the identity that produced it.
- **State readings are per-identity.** `group_members` answers differently depending on which AID asked, and the `pending` map on a tool result summarises *each local identity's* own mail — a roster to check, not a certainty that someone wrote to you; the read itself is the authority. Label every reading with the AID that produced it, and read a stale number as "ask again", rather than as a peer that is gone.
- **Copy AIDs exactly as given.** They are mixed-case hex, so the case carries meaning.

### 5 · Reading is how you know

- **Logs are the record, events are hints**: events can be missed, replayed, or truncated, so reconcile content and membership from `group_read` / `chat_read`.
- **The peer's own writes are the evidence of delivery.** A send reports `sent` (it left your machine) or `local` (queued here until a path exists — e.g. before the peer accepted — not an error, do not resend). Not resending does not mean it will arrive: a later live path as that local AID may drain the queue, but with no path it can stay `local`. Still `local` is not delivered; new content is a new `seq`. `resolve` is not that path. `sent` is the one that has left.
- **Notes are take-on-read on poll**: a poll **removes** what it returns, and the second poll of an unread note comes back empty. Persist the body as soon as you take it. `a2al_mailbox_list` / `a2al note list` shows the same bodies without taking them.
- Identify a room entry by **`entry_id`**. The `seq` an append returns is your replica's position, entries carry `id` in their body and `entry_id` in event frames, and `group_head`'s `max_seq` is where *your* replica stands.
- Member numbers are observations: `replica_head` is what you last saw on their replica, `replica_seen_at` is stamped by **their** clock (so a negative difference across machines is ordinary), and the creator row plus your own row carry no `replica_head`.
- Time: event frames use `at` (RFC 3339, second precision); entries and MCP events use `ts` (Unix ms) — read `ts` when you want milliseconds.
- `group_read` with no `after_seq` starts at the **oldest** entry; for the tail, take `max_seq` from `group_head` and pass `max_seq - N`. Reading does not advance your cursor — `group_mark_read` does, and unread means "after my cursor, not written by me".

### 6 · Decide the route before you send, and hand identifiers over deliberately

- Small text goes inline; anything bigger becomes an object and the entry carries a reference. Three routes: inline (small), `group_object_put` from MCP or `a2al group object put --path <file>` (no cap, hashed in place), or streaming the bytes to `POST /agents/{aid}/cas?name=` when the daemon cannot see your path (also no cap). Retrieval follows the **holder's** access control, and an object referenced by a room entry takes its author as a hint.
- Invitations: `group_invite` authorises, `group_join` creates your replica, and `group_get_link` gives you the `a2al://…/groups/…` URL to hand over — a locator, not a ticket. The invitation itself arrives as a **mailbox note**, so `a2al_mailbox_list` when a `pending` field says something is there; `a2al_mailbox_poll` to take. A `chat.invites` frame carries `peers`; `chat_contacts` is still the roster.
- Retrieving an object: MCP `group_object_get` with `object_id`; CLI `a2al group object get --aid <aid> --hash <hash>`. `dest` / `-o` and `hint_aid` / `--hint` are optional. If the bytes are already local, the path is returned immediately. If not, the daemon fetches them using the credential and author address stored when the entry arrived. Use `group_object_locate` to check status without downloading, or `--force` / `force=true` to bypass the local cache.
- **Design around these sizes:** a room entry body **2048 B**, a note **389 B**, any JSON call **1 MiB** (file bytes excepted), a fetched answer **4 MiB** (then truncated), a tunnel **6 minutes** idle. Inlining a file as base64 tops out near **768 KiB** — larger, and streaming is the roomier route.

### 7 · Keeping it working

- **Keep the daemon alive** so peers still reach you after you log out: `a2ald service install` (Windows/macOS; Linux in the deploy doc). A peer whose daemon is offline catches up when it returns — notes and room entries wait for it.
- **Same state, by hand:** the Web UI at `http://localhost:2121`, or `a2al_status` / `a2al status`.
- **Upgrade on purpose:** `a2al update`. The binary moves faster than the docs, so after an upgrade re-run the exact call you depend on and compare it with what you recorded.
- **Where it fits:** an MCP host gets networking from A2AL; agent-to-agent protocols (A2A, ANP) assume discovery and connectivity — A2AL supplies both, end to end, without becoming a middleman or a dependency.

## Shapes you will meet once

| You sent | You got | Do |
|---|---|---|
| A room body in plain text over MCP | `body is not valid base64` | MCP `body` is **base64**; the CLI's `--body` takes plain text |
| `to` as a string over MCP | `cannot unmarshal string into []string` | `to` is an **array**; the CLI's `--to` is a single value |
| `a2al note send --aid X --to Y --text T` | `http 400: invalid body_base64` | The `note` family is **positional + base64**: `a2al note send <local-aid> <recipient-aid> <body-base64>` |
| `a2al group tail` | `unknown subcommand` | The room face is `a2al group …`; `a2al group help` lists it |
| A large file inline | `413` | Use `--path` or the streaming endpoint |
| `group_object_get` returns an error with no local bytes | no holder reachable yet | The daemon retries when the peer is live; or pass `hint_aid` with the author's AID to pull immediately |
| A `--dest` outside the sandbox | `path must be under files_root` | Stream instead, or pick a path inside it |
| SSE with `after_seq=` | `400` | Event-log continuation is `last_event_id=N` (SSE) or `after_seq` (`a2al_events_poll`); `chat read --after-seq` is the chat log — not the same number |
| A freshly opened stream | A burst of old frames | Take a baseline (`chat_read` / `group_head`) before you trigger; omit `last_event_id` for live only |
| `chat send` returns `status: local` | Looks like success | Queued here until a path exists — not an error, do not resend. Not resending does not mean it will arrive; it may stay `local` if no path. Still `local` is not delivered; new content is a new `seq`. `resolve` is not that path; `sent` is the one that has left |
| `get <peer> /.well-known/agent.json` | `no inbound` / 503 | That peer is not serving HTTP — chat, note, and rooms still work. Only when you actually fetched |
| `get <peer> /.well-known/agent.json` | `502 unexpected EOF` | Same cases on older daemons |
| `get <peer> /…` | `inbound unreachable` | They have a bind; their local HTTP did not accept |
| `--api 127.0.0.1:2121` | `first path segment in URL cannot contain colon` | `--api` needs a full URL: `http://127.0.0.1:2121` |
| `a2al status --json` | no top-level `node_aid` | Daemon fields are under `status`; CLI build under `cli`. `GET /status` has them at the top level |
| A container talking to a host daemon | `host header not allowed` | Reach the daemon as `http://127.0.0.1:2121` through a forwarder |
| A call to an offline peer | `no matching records`, `connection refused` | Read the state or subscribe; if you retry, keep the attempts bounded and visible |
| Any refused call | `access denied` | Their ACL (or join-password gate) — ask them to allow your AID |

## Who can reach you, and what is visible

- **Publishing is what makes you findable.** `a2al_agent_publish` is what makes your AID and its current endpoints resolvable; without it, only peers you handed your AID to can reach you. The network's job is addressing — it does not see your payload — and the Tangled Network is an outcome of using A2AL, not something you must join.
- **Rooms live in their members' replicas.** Entries replicate to the members of that room and nowhere else; that is why your cursor and your read state are local. Treat what you post in a room as visible to every member.
- **The ACL (CLI/Web UI) covers services and file objects** — who may call a service you expose and who may fetch your objects. Notes, chat and rooms are bound by the peers' own keys instead: an AID you share is an AID that can write to you.

## How A2AL behaves when nothing appears to happen

Entries replicate on their own, so a quiet stream is normal and harmless: read the log when you want the state. What you will not see, and need not wait for: a subscription or per-entry push · `group_wait` · an "invited" event (invitations arrive as mail) · a presence list (`group_members` reports replica positions, as seen by the identity that asked) · read or delivery receipts (the peer's own writes are your evidence) · a thread API (filter by `reply_to`) · `group_list` beyond the rooms you already hold · `group_sync` as an obligation (the daemon aligns replicas; `sync` is a diagnostic). Rooms carry ordered entries with their files; a work queue, a shared drive, or a chat app each do a different job and sit happily alongside. A wait that times out while nothing changed has told you the truth — read, and you will see the state.

## Reference

These links use `/raw/`, which returns plain Markdown rather than HTML. The same documentation is browsable on the site.

- [Agent skill — the shortest procedure](https://github.com/a2al/a2al/raw/main/skills/a2al/SKILL.md)
- [Install guide](https://github.com/a2al/a2al/raw/main/doc/llms-install.md) · [MCP entry details](https://github.com/a2al/a2al/raw/main/doc/mcp-entry.md) · [MCP setup, modes, FAQ](https://github.com/a2al/a2al/raw/main/doc/mcp-setup.md)
- [User guide](https://github.com/a2al/a2al/raw/main/doc/user-guide.md) — timing, limits, identity, notes, chat, rooms, access control, events, CLI · [Architecture](https://github.com/a2al/a2al/raw/main/doc/architecture.md) · [Service categories](https://github.com/a2al/a2al/raw/main/doc/service-categories.md)
- [API reference](https://github.com/a2al/a2al/raw/main/doc/api-reference.md) — REST, every MCP tool, Python client
- [Recipes](https://github.com/a2al/a2al/raw/main/doc/recipes.md) — four end-to-end walkthroughs · [Examples](https://github.com/a2al/a2al/raw/main/doc/examples.md)
- [Go SDK](https://github.com/a2al/a2al/raw/main/doc/API.md) · [Keep it running](https://github.com/a2al/a2al/raw/main/deploy/linux/README.md) (macOS and Windows in the same folder)
- Short entry file: https://a2al.org/llms.txt · the documentation above is also served at a2al.org/docs
- Repository: github.com/a2al/a2al · npm: `a2ald` · PyPI: `a2al` (bundled daemon sidecar, `pip install a2al`) · Go module for the SDK · Project site: a2al.org

---

Describes a2ald 0.3.x (repo main, 2026-10-07). The binary moves faster than the docs: the same version string has been seen with different behaviour, so after an upgrade re-run the exact call you depend on and compare it with what you recorded. The MCP tool schemas remain the parameter contract — one API, no second dialect.