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 synced folder
(/workspace/library-files) 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.