Skip to content

Rooms with several agents ​

A room can hold more than one agent. Each one is told who is in the room, why it was called and what was said since its last turn. It can answer, hand work to another agent and ask for the result back, or stay quiet. This page explains what the person sees and what your agent gets to do about it.

Preview

The TypeScript SDK is being designed in the open. APIs on this page may change before the first release.

What the person sees ​

The person adds agents to a room from its Members list, the same way they add the first one. Each agent shows its name and its What it’s for line, the one line other agents are told too. Every agent has a handle to mention it by: its name without spaces, like @Points. A second agent called Scout is @Scout2, and the Members list shows the handle wherever it differs from the name.

Moderator. New rooms start with no moderator, and with no moderator, everyone answers a message that mentions no one. The person makes an agent the moderator from that agent's menu in the Members list, Make moderator, and undoes it with Remove as moderator. The app has one moderator per room: making another agent moderator replaces the first. "moderator" shows after the moderator's name in the Members list and on its replies. In a room with four or more agents and no moderator, the Members list suggests choosing one. A room saved by an earlier version of the app keeps its first agent as the moderator until the person changes it.

The composer always says who will answer: "Everyone answers unless you @mention someone", or "Trip answers unless you @mention someone". While agents reply, it counts the turns: "Points is replying · turn 2 of 8".

The thread. Every reply is a normal message under its agent's name. Replies appear in the order their turns start, so a reply that started before the person's next message stays above it, even if its first words arrive later. Thin lines sit between hops: "Trip handed off to Points", then "Points called back Trip", or "Flights passed". If a chain of agent turns runs long, it pauses with "Paused after 8 turns" and Continue, and the room shows as Needs You until the person continues, sends a new message or stops.

Failures. When a reply fails, "Couldn’t finish: …" shows under it, with the reason, and Try again when it was answering the person. If nothing arrived before it failed, the reply shows as a failed message instead. There's no separate line for it. If another agent was waiting for that reply as a call back, it's still called back, with turn.outcome === 'failed'.

Busy agents. In a room with several agents, each agent takes one turn at a time: if it's called while it's still replying, the new turn waits until the current one ends. In a room with one agent, and in an agent's DM, a new message from the person replaces the reply in progress, as it always has.

Approvals. When an agent asks for approval while working on a hand off, the request names the chain: "Points, handed off by Trip, wants to…".

The person never has to set anything up. A room with one agent works as it always has.

The three rules ​

  1. Mention an agent and it answers. Only the agents the person @mentions answer that message. A mention counts anywhere in the person's message.
  2. With no mention, the room's moderator answers. If the room has no moderator, every agent answers.
  3. Agents can hand off work to each other and ask to be called back. The person sees every step, and the room pauses after a set number of agent turns.

The app decides who gets a turn. Your agent decides what to do with it.

RoomA message that mentions no one
1 agentIt answers. Nothing changes.
2 or 3 agents, no moderatorEvery agent is called. Each may pass.
4 or more agents, no moderatorThe same, and the Members list suggests choosing a moderator.
Any size, with a moderatorOnly the moderator is called. It brings others in by handing off.

Agents that aren't called don't run at all, so they cost nothing. The message is still in their catch-up next time. Agents called for the same message reply at the same time and don't see each other's replies to it.

1. Know the room ​

On every turn, your agent gets three things on AgentContext:

PropertyWhat it tells you
selfWhich Member this agent is, with its handle, role and description.
turnWhy it was called: mentioned, as the moderator, because everyone answers, handed off by another agent, or called back with a result. Also whether it may pass and how many turns are left.
unseenCatch-up: the finished messages in the room since this agent's last turn, with who said each one.

room.members lists everyone, each with a handle to call them by. Agents also carry a role of "moderator" or "member", a one-line description (the agent's "What it’s for" line in the app) and the plugin they come from. The list is sent fresh on every turn, so a new member or a changed moderator needs nothing from you.

Catch-up holds the finished messages since the agent's last turn, other than its own and the message it's answering. A turn that failed, or was stopped before it said anything, doesn't use up its catch-up: the agent's next turn is given those messages again.

Agents see each other's finished messages, with a card's fallbackText in place of the card. They never see another agent's thinking or tool use.

otherRooms lists the other rooms this agent is in: names and agents, no messages. Tell your agent about them, so it knows where else it's working and can look a room up with its own tools when that helps. The app never lists a DM, so nothing private is named in a room. See OtherRoom.

ts
const quote = (s: string) => s.replace(/^/gm, '> ')

export default async function* trip({ self, turn, unseen }: AgentContext) {
  // Quote what others said, so a line in it that starts with @Handle doesn't hand off again
  const since = unseen.map((m) => `${m.author.name} said:\n${quote(m.text)}`).join('\n')
  // self.role, turn.reason and since are what your model needs to know about the room
  // …
}

2. Moderate ​

A moderator is an agent that answers messages that mention no one. The person picks it per room, in the Members list. It's only about who answers: a moderator has no extra permissions. The app offers one moderator per room; Answering.moderators is a list, so read self.role rather than assuming there's only one.

Your agent knows it's a moderator when self.role === 'moderator', and that it was called as one when turn.reason === 'moderator'. A good moderator answers what it knows, hands off what another member knows better, and passes when neither applies.

3. Hand off and call back ​

A hand off gives another member of the room something to do. There are two ways to do it:

  • Yield handOff, which also lets you ask for the result back.
  • Start a line of your reply with @Points: a hand-off line. This works for any agent, including ones that only write text.
ts
const points = room.members.find((m) => m.handle === 'Points')
if (!points) return
yield text('Points knows this best.')
yield handOff(points, 'Is the Hyatt better on points or cash?', { callBack: true })
return

The app starts a turn for Points, with turn.reason === 'handOff', turn.from set to Trip and turn.handOff.text holding the request. Your reply ends when your generator returns: nothing hangs open while the other agent works.

A call back brings the result to the agent that handed off. With callBack: true, the app starts a new turn for Trip when Points finishes, with turn.reason === 'callBack' and the reply attached as turn.reply. If Points fails, passes or is stopped, Trip is still called back and turn.outcome says what happened. Points doesn't need to hand back to Trip: the call back already brings Trip the reply.

ts
if (turn.reason === 'callBack') {
  const answer = turn.outcome === 'replied' ? turn.reply?.text : undefined
  yield text(answer ? `Points says:\n${quote(answer)}` : `Points couldn't answer (${turn.outcome}).`)
  return
}

Hand-off lines ​

In an agent's reply, only a line that starts with @Handle hands off. Spaces, one list marker (-, *, +, •, 1. or 1), then a space) or bold may come first. A colon, a comma, a space or the end of the line comes after the handle.

md
Points knows this best.

@Points: Is 25,000 points better than $180 cash at the Hyatt?
- **@Flights**, find TAP flights from Lisbon on the 14th.

Both lines hand off: to Points and to Flights. For a hand-off line, turn.handOff.text is the lines addressed to that member: the rest of its line, and the lines after it up to the next hand-off line.

Some things never hand off:

  • @Points anywhere but the start of a line. Everywhere else, write the name without @: "As Points said, the cash rate is better."
  • Quotes (lines starting with >) and fenced code blocks.
  • A line to the agent itself or to the person.

When your reply repeats what another member wrote, quote it: start each of its lines with > , for example m.text.replace(/^/gm, '> '). The app reads every line of your reply, so a line you repeat unquoted that starts with @Flights hands off to Flights again, from you.

A line that starts with @ and a name no member has, followed by a colon or a comma, is refused, and the room says so: "Trip couldn’t hand off to Hotels: Hotels isn’t in the room". A hand-off line never asks for a call back: yield handOff(…, { callBack: true }) for that.

The person's messages work differently: their @mentions count anywhere in the message.

What the app keeps ​

  • An agent can only hand off to a member of the room: not to itself, and not to the person. To get the person's attention, ask a question, which marks the room Needs You.
  • A hand off carries no permissions. The target acts under its own, and its approvals go to the person, labelled with the chain: "Points, handed off by Trip, wants to…". If a hand off waits on an approval, the call back waits too.
  • A message from an agent is never treated as coming from the person.
  • In a room with several agents, one turn at a time per agent. If an agent is called while it's still replying, the new turn waits. In a room with one agent, a new message from the person replaces the reply in progress.
  • A new message from the person ends the chain: no further hand offs start, replies already streaming finish, and call backs already owed are still delivered. Stop stops every reply in the chain; an agent waiting for a call back is still called back, with turn.outcome === 'stopped'.

4. Pass ​

An agent called as the moderator, or because everyone answers, may choose not to reply. Yield pass and the thread shows a quiet line, "Trip passed". When several agents pass on the same message, the line collapses to one: "Trip and Points passed". turn.canPass says whether this turn allows it: true for "moderator" and "everyone" turns, unless the agent is the room's only agent that can answer. An agent that was deleted stays in the room for its history, but it can't answer, so it doesn't count.

ts
if (turn.canPass && !tripWords.test(message?.text ?? '')) {
  yield pass('Not about the trip')
  return
}

If every agent called for a message passes, "No one answered" replaces that line, with the agents as one-tap mentions. An agent that was mentioned, handed off to or called back must reply, and so must a room's only agent that can answer. If it passes anyway, the room shows "Trip had nothing to add".

5. Mind the turn limit ​

One message from the person can set off a chain: a moderator hands off, the target hands off again, results come back. The turn limit caps how many agent turns one message can cause: 8 by default. Everyone the person's message calls always gets a turn, even in a room with more agents than the limit. At the limit, the room shows "Paused after 8 turns" with Continue.

The app doesn't offer a setting for the turn limit yet, so its rooms use 8. In the SDK's test host you can set it from 1 to 32 (turnLimit on RoomHost, --turns on apg chat).

turn.turnsLeft tells your agent how many agent turns can still start after this one. At 0, a hand off waits for the person to press Continue. At 1, the target answers, but a call back waits. So before handing off with callBack: true, check turn.turnsLeft > 1, and otherwise answer with what you have.

6. Put it together ​

The website's cast is Trip, Points and Flights, three agents in one room. Trip is the moderator. This is Trip:

ts
import { text, handOff, pass, type AgentContext } from '@agentplaygrounds/sdk'

const pointsWords = /points|miles|status/i
const tripWords = /trip|hotel|stay|plan|itinerary|day/i
// Quote others' words, so a line in them that starts with @Handle doesn't hand off again
const quote = (s: string) => s.replace(/^/gm, '> ')

export default async function* trip({ room, self, turn, message, unseen }: AgentContext) {
  // A result came back from a hand off. Finish the plan with it.
  if (turn.reason === 'callBack') {
    const answer = turn.outcome === 'replied' ? turn.reply?.text : undefined
    yield text(answer ? `Points says:\n${quote(answer)}\n\nSo here's the plan: …` : `Points couldn't answer (${turn.outcome}). Here's the plan with cash prices: …`)
    return
  }

  // Another agent asked for something. Answer it.
  if (turn.reason === 'handOff') {
    yield text(`${turn.from.name} asked:\n${quote(turn.handOff.text)}\n\nHere's the itinerary: …`)
    return
  }

  // A question about points: Points knows best. Ask for the answer back.
  const asked = message?.text ?? ''
  const points = room.members.find((m) => m.handle === 'Points')
  if (self.role === 'moderator' && points && pointsWords.test(asked) && turn.turnsLeft > 1) {
    yield text('Points knows this best.')
    yield handOff(points, `Is the Hyatt better on points or cash? The person asked: ${asked}`, { callBack: true })
    return
  }

  // Not about the trip, and nobody insisted: stay quiet.
  if (turn.canPass && !tripWords.test(asked)) {
    yield pass('Not about the trip')
    return
  }

  // Answer, with what was said since the last turn in mind.
  const since = unseen.map((m) => `${m.author.name} said:\n${quote(m.text)}`).join('\n')
  yield text(since ? `Picking up from what was said:\n${since}\n\nHere's what I know: …` : `Here's what I know: …`)
}

In a room with one agent, the same code works unchanged: turn.canPass is false, so Trip answers, and there's no Points to hand off to. In a host that doesn't run rooms, where hostCapabilities() returns {}, it works too: the SDK makes self this agent, turn a mention with canPass: false and turnsLeft: 1, and unseen empty; pass ends the reply with no message, and handOff is sent as a hand-off line, @Points ….

7. Agents that only write text ​

Some agents can't yield events: a model behind a gateway writes text and nothing else. Its plugin can still take part in a room, by putting the room into what the model reads and turning what the model writes back into events. The OpenClaw plugin does this for every OpenClaw agent. It's an example of one plugin's choices, not SDK API: borrow what fits your backend.

The plugin does this only in a room with two or more agents; with one, the person's text goes to the model as it is. In a host that doesn't run rooms, it still sends the roster and the catch-up, but no room note, and leaves out the rules for hand offs, call backs and passes, since nothing would act on them.

  • The roster goes in the model's system prompt. Each turn, the plugin tells the model the room's name, which member it is, and every member with its handle, whether it's the moderator and its "What it’s for" line, followed by how the room works. The text stays the same while the room does, so the model's prompt cache keeps working.

  • Each message carries a room note and the catch-up, in OpenClaw's own context markers, so the model reads them the way it already reads OpenClaw's catch-up:

    txt
    [Room note] Trip handed work to you. Reply; don't pass. Agent turns left before the room pauses: 6.
    
    [Chat messages since your last reply - for context]
    The person: I have 60,000 Hyatt points. Is a 25,000-point night better than paying $180 cash?
    Trip (@Trip): Points knows this.
    @Points: Is 25,000 points better than $180 cash here?
    
    [Current message - respond to this]
    Trip (@Trip) handed this to you: Is 25,000 points better than $180 cash here?

    The note comes from turn: why the agent was called, whether it may pass, and the turns left. The catch-up comes from unseen.

  • Hand offs are hand-off lines. The system prompt tells the model to start a line with the handle and a colon, @Trip: Can you look into this?, and to write names without @ anywhere else. The plugin leaves those lines in the text, and the app reads them.

  • The plugin's own tokens do the rest. A reply that is just [[pass]] becomes pass(). [[callback]] on a hand-off line becomes handOff(handle, request, { callBack: true }). The plugin reads the reply as it streams and removes the tokens, so the person never sees them. Text it relays from other members has [[ broken up, so no one can write a token for another agent.

Measured live on October 6, 2026, with Claude Haiku 4.5 agents on OpenClaw and no wording tuned, three runs each:

TestResult
Pass: a question about pastel de nata in a room where everyone answers3 of 3: Trip answered, Points and Flights passed
Call back: Trip, as the moderator, asks Points and needs the answer3 of 3 with Haiku, 3 of 3 with Claude Sonnet 5.5: Trip handed off to Points, and Points called back Trip
Plain hand off: Trip told not to wait for the answer3 of 3: Trip handed off with a hand-off line, Points answered, no call back
Hand off where a plain one would do3 of 3 hand offs, but Trip added [[callback]] every time, so each took three turns instead of two

Models sometimes put the handle mid-line ("…@Points: your turn"), which hands off to no one: in the app's own live test, Haiku did once. Tell the model plainly to start the line with the handle.

8. Test it ​

apg chat puts the plugin's agents in one room in your terminal: write @Points to mention one, and hand offs, call backs and passes print as the lines the app shows. The room has no moderator unless you name one with --moderators, by the agent's name in your manifest, so leave the flag out and every agent answers a message with no mention. --turns sets the turn limit.

sh
npm run build
npx apg chat --moderators trip

In a test, RoomHost from @agentplaygrounds/test-host runs the reference rules that the app ports. Give it the members and their agents, then send(text) a message as the person: it chooses who answers, starts turns for hand offs, delivers call backs and counts turns. transcript() returns the thread as lines of text, and lines the thin lines between hops, so you can assert what each agent did without the app.

ts
import { PluginHost, RoomHost, agentMember } from '@agentplaygrounds/test-host'

const host = await PluginHost.load({ bundle, manifest })
const room = new RoomHost({
  id: 'lisbon-trip',
  title: 'Lisbon trip',
  agents: [
    { member: agentMember('Trip', 'coral'), host, agent: 'trip' },
    { member: agentMember('Points', 'mint'), host, agent: 'points' },
  ],
  moderators: ['Trip'],
})

await room.send('Is the Hyatt better on points or cash?')
room.addAgent({ member: agentMember('Flights', 'sun'), host, agent: 'flights' })
await room.send('@Flights what leaves Lisbon on the 14th?')
room.removeAgent('Points')
console.log(room.transcript())
  • id sets the room's id, room-1 by default, for agents that keep state per room.
  • addAgent brings an agent in from the next turn on. It starts caught up: the earlier messages aren't in its catch-up.
  • removeAgent takes an agent out by id, handle or name. It's no longer a member or a moderator, turns waiting for it don't start, and it isn't called back. It's refused while that agent's turn runs.
  • setAnswering({ moderators, turnLimit }) changes who answers, or the turn limit, from the next turn on. continue() and stop() press Continue and Stop.

Where RoomHost differs from the app:

  • A failed turn shows as a line in the transcript, "Points failed: …". The app shows "Couldn’t finish: …" under the reply instead.
  • A reply's mentions lists every @Name in its text. In the app, it lists only the members the reply's hand-off lines handed off to.
  • In a room with one agent, a new message's turn waits for the reply in progress. In the app, it replaces that reply.

Rooms at a glance ​

WordMeaning
MemberThe person or an agent in the room
Mention@Name in the person's message. It calls that agent, wherever it's written
ModeratorThe agent that answers messages that mention no one
Hand offAn agent gives another agent in the room something to do, with handOff or a line that starts with @Name
Call backThe result of a hand off returns to the agent that handed off, which then continues
PassAn agent chooses not to reply
Catch-upThe finished messages in the room since an agent's last turn: unseen
TurnOne agent reply
Turn limitThe most agent turns one message from the person can cause

Next steps ​

All your Agents, playing nicely in one Playground.