> ## Documentation Index
> Fetch the complete documentation index at: https://docs.attaxr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent collaboration

> Register agent identities and exchange messages through the Aquila agent mailbox.

The Aquila MCP server carries an agent mailbox beside its tools. Every
MCP client you connect can register a stable identity and exchange
persistent messages with the other agents on your account. A lead agent
hands a scoped task to a specialist. The specialist answers in the same
thread. No direct agent-to-agent connection is needed: both agents talk
only to the server, and both use the same URL and key as every other
tool.

## Supported agents

Any client that speaks MCP can join the mailbox. The setup guides cover
[Claude Code, OpenCode, Cursor, and Codex](/mcp/setup); a harness you
wrote works the same way. Each running agent picks its own stable name,
for example `claude-code`, `codex-recon`, or `ci-worker`.

<Note>
  Hackbot coordinates its own sub-agents inside a scan. That
  orchestration is part of Hackbot and needs no mailbox setup. The
  mailbox on this page is the MCP surface for the agents you connect
  yourself.
</Note>

## Authenticate

The mailbox rides the MCP server, so it uses the same endpoint and key
as every other tool:

```
Authorization: Bearer aqmcp_YOUR_KEY
```

All nine mailbox tools are listed in the
[tool surface](/mcp/overview#tool-surface). One account is one mailbox
namespace. An agent sees only the agents and messages of its own
account. A forged or foreign id answers not found.

## Register an identity

Call `agent_register` once at the start of each agent session. Send a
`name`, and optionally a `description` (one line that other agents
see), a `kind` label (for example `claude-code` or `worker`), and a
`sessionLabel`.

The name is the identity key. The server lowercases it, strips
everything except letters, digits, and hyphens, and caps it at 64
characters. `Claude Code` and `claude-code` register the same agent.
Registration is idempotent: the same name always returns the same
agent id.

The call returns the agent's `agentId` and a `sessionId`. Record both.

## Sessions

The server mints session ids; a client never invents one. To resume a
session, pass its id back in `sessionId`. Omit `sessionId` to start a
new session. Use `sessionLabel` to name the work in the session.

An agent counts as active for 5 minutes after its last mailbox call.
Every mailbox call stamps activity, so a working agent stays active
without extra pings.

## Discover other agents

`agent_list` returns the registered agents of your account, most
recently active first. Each row carries the agent id, name,
description, kind, an `active` flag, the unread message count, and the
session count. Narrow it with `query` (a substring on name or
description) or `onlyActive`. `agent_get` fetches one agent by id or
name, with its recent sessions.

## Send messages

`send_message` starts a new thread:

| Argument | Required | Meaning |
| - | - | - |
| `agentId` | Yes | Your own agent id from `agent_register`. |
| `to` | Yes | The recipient's agent id or exact stable name. |
| `content` | Yes | The message body: the full context the reader needs. |
| `subject` | No | One line. Capped at 200 characters. |
| `scanId` | No | A scan to attach as context. |
| `metadata` | No | A JSON object with extra context. Capped at 8 KB. |

Content is capped at 50,000 characters. The recipient must be a
registered agent of your account. The response carries the new
`threadId`.

`reply_message` answers inside an existing thread. Send your `agentId`,
a `replyTo` message id (any message you sent or received in that
thread), and the `content`. The reply inherits the thread and the scan
context of the message it answers. You cannot reply into a thread you
cannot see.

## Read the inbox

Delivery is pull-based. A stored message is delivered; nothing pushes
to the recipient. The recipient finds mail when it reads.

* `get_mailbox` returns the newest messages for your agent, newest
  first, plus a per-sender summary with totals and unread counts.
  Filter with `unreadOnly`. `limit` defaults to 20 and caps at 100.
  List views cap content at 1,000 characters per message.
* `get_messages` returns one thread, oldest first, with full content.
  Pass `threadId`, or a `messageId` whose thread the server resolves.
  `since` (RFC 3339) keeps only newer messages. `limit` defaults to 50
  and caps at 200.
* `get_message` returns one message with its full body.

You can read a message only when you sent it or it is addressed to
you. Anything else answers not found. This is the authorization rule,
not a leak.

## Track message state

`mark_message` moves received messages forward. Send 1 to 100
`messageIds` and a `status` of `read` or `ack`. `ack` implies read.
State only moves forward, so repeated calls are safe. The response
reports each id's resulting `readAt` and `ackAt`.

## Scan context

`scanId` on `send_message` labels the message with a scan. Replies
inherit it. The mailbox never touches scan targets and injects no
scope: the label travels with the message, and the target-bearing
tools still enforce the scan's approved scope on their own.

## Agent collaboration

The mailbox lets an orchestrator and sub-agents divide a task without
direct connections, shared networks, or shared processes. Each agent
only talks to the server.

1. Each agent calls `agent_register` and records its `agentId`.
2. The orchestrator calls `agent_list`, picks a specialist, and hands
   over the task with `send_message`: subject, full task context in
   `content`, and the `scanId` to work under.
3. The specialist polls `get_mailbox`, reads the task with
   `get_messages`, runs its work — often the recon tools on the
   approved scope — and answers with `reply_message` in the same
   thread. It marks the task message `ack`.
4. The orchestrator polls its own mailbox and reads the result. The
   thread keeps the whole exchange, so a third agent can pick the
   context up later.

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# Lead agent (claude-code)
send_message   { "agentId": "<lead-id>", "to": "recon-runner",
                 "subject": "Map acme-labs.com",
                 "content": "Enumerate subdomains and probe live hosts.
                             Reply in this thread with evidence.",
                 "scanId": "<scan-id>" }

# Worker agent (recon-runner), on its own schedule
get_mailbox    { "agentId": "<worker-id>", "unreadOnly": true }
get_messages   { "agentId": "<worker-id>", "messageId": "<task-message-id>" }
# ... runs subfinder, httpx, and katana on the approved scope ...
reply_message  { "agentId": "<worker-id>", "replyTo": "<task-message-id>",
                 "content": "12 live hosts. 3 with exhaustive directories.
                             Evidence and endpoints in this thread." }
mark_message   { "agentId": "<worker-id>", "messageIds": ["<task-message-id>"],
                 "status": "ack" }

# Lead agent, on its own schedule
get_messages   { "agentId": "<lead-id>", "messageId": "<reply-message-id>" }
```

The two agents never address each other directly. The mailbox holds
the exchange, so an agent that is between runs misses nothing and
rejoins with its history intact.

## Tool reference

| Tool | Reads or writes | Purpose |
| - | - | - |
| `agent_register` | Write | Mint or resume the agent identity and its session. |
| `agent_list` | Read | List your account's agents with live state. |
| `agent_get` | Read | Fetch one agent's profile and recent sessions. |
| `get_mailbox` | Read | Read the inbox with the per-sender unread summary. |
| `get_messages` | Read | Read one thread, oldest first, with full content. |
| `get_message` | Read | Fetch one message with its full body. |
| `send_message` | Write | Start a thread to another registered agent. |
| `reply_message` | Write | Reply inside a thread you can see. |
| `mark_message` | Write | Advance received messages to `read` or `ack`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.