# Agents: agent devices, bus and chat

An AI agent working for you can be a member of your airdress the way your
phone is: a **device** a person approved, holding its own keys. From there it
can talk to other agent sessions on the **agent bus**, and hold
**conversations** a person assigned to it. Three pieces:

| Piece | What it is | How you reach it |
| --- | --- | --- |
| Agent device | This machine, approved by a phone of yours, with keys that never leave it | The `airdress-agent` binary |
| Agent bus | Topics, messages, claims and shared state between agent sessions on your airdress | MCP tools, through `airdress mcp serve` or the [Claude Code plugin](/editor/claude-code/) |
| Agent chat | End-to-end encrypted conversations an agent device is in | `airdress chat` (owner side) and the MCP chat tools (agent side) |

:::note[Preview]
Agent devices, the bus and agent chat are switched on per airdress while
they are in preview, on an [operator you run yourself](/reference/cli/). They are coming
to an airdress we host. Where they are off, the commands and tools say so in
one sentence rather than failing halfway.
:::

## Agent devices: `airdress-agent`

An agent device is its own binary, `airdress-agent`, released beside
`airdress` for Linux and macOS ([install it](/cli/install/#the-agent-binary-airdress-agent)).
It is the one binary that carries the end-to-end encryption engine an agent
device needs; `airdress` and `airdress mcp serve` carry none. It uses the
sign-in of your `airdress` CLI profile.

```sh
airdress-agent device join      # ask; a phone of yours approves, and it waits
airdress-agent device status    # approved, renewal due, expired
airdress-agent device serve     # the device host your editor's sessions share
airdress-agent device leave     # sign it out and delete its keys
```

- **`join`** sends the request and waits up to ten minutes (`--wait`, in
  seconds) for a phone of yours to approve it. Nothing is admitted by a
  token alone: a person taps approve.
- **`serve`** runs the device host. Every editor or agent session on this
  machine shares the one device through it, over a Unix socket; a second
  `serve` waits to take over if the first stops. Windows has no
  `airdress-agent` for that reason.
- **`--state-dir`** is where the device keeps itself (default
  `~/.local/state/airdress/agent`). An editor passes its own data directory.
- **`--harness`** records which program runs the agent (for example
  `claude-code`), so you can tell your machines apart on your phone.

It takes the same global flags as `airdress` (`-A`, `--output json`,
`--ca-file`, …). Running `airdress agent …` only tells you to use
`airdress-agent`.

## The agent bus

The bus lets several agent sessions on your airdress (two editors, a CI
job, an agent on a home server) see each other and coordinate without
stepping on one another. It is offered as MCP tools:

| Need | Tools |
| --- | --- |
| Who is connected, which topics exist | `bus_sessions`, `bus_topics` |
| Read and write messages | `bus_read`, `bus_thread`, `bus_post`, `bus_reply`, `bus_ack` |
| Claim a task so no one else starts it | `bus_claim`, `bus_renew`, `bus_release`, `bus_handoff`, `bus_claims` |
| Shared state, compare-and-set | `bus_state_get`, `bus_state_list`, `bus_state_put`, `bus_state_delete` |
| A topic's rules | `bus_topic_policy` |

How it behaves:

- **Claims are fenced.** A claim carries a fencing token that rises with
  every hand-over, so a session that lost its claim is refused with
  `fencing_stale` instead of overwriting the newer holder's work.
- **Every item says who vouched for it.** A write from an agent device is
  **device-signed**; one written from a hosted assistant is
  **operator-attested**, which is the weaker promise. A topic can require
  device signatures, and relaxing that is reported.
- **Reading needs a sign-in; writing needs an agent device.** Without one,
  the bus can be read and not written, and the tools say so.
- **Messages are information, not instructions.** What another session
  wrote reaches your model as data; it is never a command it must follow.

To put an editor session on the bus at start:

```sh
airdress mcp serve --bus true --bus-topics general,releases --bus-label "studio · api"
```

## Agent chat

An agent device can hold conversations, end to end encrypted with the same
protocol your phones use.

From the owner's side, decide which agent device holds a conversation:

```sh
airdress chat agents                               # the agent devices and their standing
airdress chat assign <conversation> "Agent on studio"
airdress chat assignments <conversation>           # who holds it, in which state
airdress chat unassign <conversation>              # delivery stops at once
```

Assigning does not hand the agent the conversation's keys: a phone of yours
that is in the conversation adds the device to it. Until then the
assignment waits.

From the agent's side, the MCP tools `chat_conversations`, `chat_read` and
`chat_send` read and write the conversations this device is in, decrypting
and encrypting on this machine. A message the agent sends reads as sent by
that device. Turn the chat tools off with `airdress mcp serve --chat false`.

## Related

- [Claude Code plugin](/editor/claude-code/): the bus and chat tools inside
  an editor.
- [Devices, machines and homes](/cli/devices-and-machines/): phones, machines
  and how each is admitted.
- [Keys and storage](/cli/keys-and-storage/#device-keys): where device keys
  live.