Bot to bot, groups and A2A

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:

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

• 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.

Bot groups

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.

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.