Peer messaging
Let one saved bot ask another for help or information, and optionally share a single workspace file, without a shared group.
Two of your saved Cluster Bot Computers — top-level root sessions, not local sub-agents — can exchange a message directly, without belonging to the same group. The sender keeps working; the recipient's final answer is delivered back automatically in a later turn.
Scope
Peer messaging is limited to Cluster Bot Computer root sessions. Both the
sender and the recipient must use the built-in agent_cluster-bot agent with
the Computer profile, must not be members of a group,
must not be archived, and must be running (a saved, provisioned
environment with a live sandbox). Both must be
owned by the same actor in the same organization. A peer request never grants
the recipient permission for consequential actions, and it can't read the
other bot's private conversation history.
Tools
Peer messaging is exposed as two built-in tools. They are not part of the
tools catalog for user-created agents and cannot be attached to one; the
service adds them to a Cluster Bot Computer root session's model request only
during a turn started by a signed-in human (never during a turn started by
another peer's message):
| Tool | Description |
|---|---|
list_root_agents | Lists the caller's other available saved bots by immutable ID. Read-only. |
message_root_agent | Sends { target, message, file } to another saved bot by exact ID and returns once the request is durably accepted — not once the recipient has answered. |
file is required by the schema but nullable: send null for a text-only
request, or a path relative to the sender's own mounted workspace to share
one file. Within the same user turn, sending the same target and request
again reuses the original exchange instead of creating a duplicate; a retry
that omits a file the original request included is rejected with 409.
File sharing
Sharing a file captures an immutable snapshot of the sender's synced copy — up to 18 MiB, one regular file, no directories or symlinks — and delivers an independent copy into the recipient's own workspace before its turn starts. Later edits on either side never change the shared snapshot:
- Editing the sender's original after sharing does not change what the recipient (or the conversation attachment) sees.
- The recipient may freely edit its own copy; that never reaches back to the sender.
- Sharing an edited file again produces a new, separate snapshot.
A moving, unsynced, or oversized file fails the request outright rather than silently sharing stale content.
Exchange lifecycle and API
Each peer request is a durable peer exchange, viewable and stoppable through the HTTP API:
| Method | Path | Description |
|---|---|---|
GET | /v1/peer-exchanges/{id} | Get the exchange: request, answer, current phase/state, and attachment (null or {id, filename, content_type, size, sha256}). |
POST | /v1/peer-exchanges/{id}/stop | Stop that exchange only — it does not cascade to unrelated peer work. |
GET | /v1/peer-exchanges/{id}/attachment | Download the exchange's retained file bytes, if any, as application/octet-stream. Requires normal actor/org access to both bots; an inaccessible or revoked attachment fails closed rather than falling back to a live file. |
All three endpoints take the caller's Bearer JWT and a ?org_id= query
parameter like the rest of the API — see
API reference.
Limits
- At most four distinct peer targets may be addressed from one user turn.
- A bot that received a peer request cannot itself send further peer requests in the same turn (no nested delegation yet).
- Peer messaging is unrelated to the
clusterCLI's root-agent messaging (which uses the same tool names but only reaches local interactive sessions sharing a~/.clusterdata root) and to its local child agents.