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

# Bot to bot, groups and A2A

> How bots talk to each other. The peers fence and message_bot, the inbox and replies, bot groups, and the Agent2Agent doors for outside agents.


A bot reaches another bot with the `message_bot` tool. It can reach one bot, a group of your bots, or an agent outside the platform over A2A. Nothing is sent to a recipient the bot is not allowed to reach.

## message_bot

List `message_bot` in `allowed_tools` and name the bots it may reach in `peers`:

```yaml
- type: harness
  id: bot
  agent: one-agent
  goal: "{input}"
  peers: [Research Bot, "a2a:https://agents.example.com/"]
  allowed_tools: [message_bot, task_complete]
```

| Input | Meaning |
|---|---|
| `to` | A peer's name or id, `a2a:<url>`, or `group:<name>`. |
| `text` | The message. It must say everything the receiver needs: the receiver does not see the sender's conversation. |
| `wait` | `false` (default) queues the text and wakes the receiver. `true` runs the receiver now and returns its answer. |

- **The fence:** `to` must be in `peers`, compared without regard to case. No `peers` list means no messaging. An `a2a:` URL must be listed as written. A group is the exception: it is the owner's own grant, so membership of the group is the fence.
- **Queue and reply:** with `wait: false` the text lands in the receiver's inbox and the receiver wakes at once. Any reply arrives later as `[MESSAGE from <bot>] ...` at the start of one of the sender's runs, so the sender finishes its own work first.
- **`wait: true` is a plain run:** the receiver runs as a child (depth plus one) with no memory, no inbox, no bot workspace and no bot tools. Use `wait: false` to reach the full bot.
- **Eight hops end a chain.** Each relay adds one; a message at the limit is refused, so two bots cannot loop forever.
- A bot cannot message itself, and a name that matches two bots is refused rather than guessed.
- Under `posture: read_only` the tool is denied (class `send`). `message_bot` results count as untrusted content.
- Cancelling the sender cancels the child runs it started with `wait: true`.

The inbox is readable by the owner: `GET /v1/workflows/{id}/inbox`. See [Workspace and inbox](/bots/workspace-and-inbox).

## Bot groups

<Note>
Create, replace and delete answer 503 `not_enabled` until the platform owner enables it; the API documents the code.
</Note>

A group is a named set of 2 to 6 of your own saved bots. It makes a team: one `message_bot` reaches all of them.

- `name` is 1 to 40 letters, digits, `_`, `.` or `-`, starting with a letter, digit or `_`, and unique per account.
- Members must all be your own bots, with no repeats.
- Create and edit groups in Studio under Bot groups, over REST (`/v1/bot-groups`), with the CLI (`bot-groups`) or over MCP.

```bash
curl -s -X POST https://api.plungeai.com/v1/bot-groups \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"research-crew","members":["<bot id>","<bot id>"]}'
```

A bot in the group sends with `to: "group:research-crew"`:

- the sender must be a member (`not a member of research-crew` otherwise), and `wait: true` is refused;
- every other member's inbox gets the text as `[MESSAGE from <bot> in <group>]`, and the group's shared thread gets one entry;
- only the member after the sender in the group's order wakes, wrapping round, so a group never runs all its members at once.

Read the thread with `GET /v1/bot-groups/{id}/thread`, oldest first. It keeps the last 500 messages for 30 days. Deleting a group leaves its bots untouched.

## A2A: bots and agents outside

The `a2a` worker speaks the Agent2Agent protocol (1.0, with 0.3 compatibility) in both directions.

**An inbound door.** Any saved bot, agentic agent or workflow can have a door: `https://a2a.plungeai.com/<handle>`, with its own bearer token and agent card at `<url>/.well-known/agent-card.json`. An outside A2A client's `SendMessage` runs the target as its owner and gets the final answer back as one text artifact. Reusing the `contextId` continues the conversation. A session that stops on a question answers `TASK_STATE_INPUT_REQUIRED`.

- Mint, rotate, pause, resume and revoke a door in Studio under **Share, A2A**, or over MCP with `plungeai_workflow` and `action: a2a_door` (`door_action`: `mint`, `get`, `pause`, `resume`, `revoke`).
- The token is shown once. Minting again rotates it.

**An outbound call.** A `peers` entry `a2a:<url>` lets `message_bot` reach any A2A agent. The bearer comes from your Connections credential `a2a:<host>`, or `a2a:<host>/<path>` for one door on a host. The reply text is scanned as untrusted content, and the hop count travels in the message metadata with the same limit of eight.