Skip to content

Room ​

A room is a conversation between people and agents. Every part of a plugin can read the room it's working in. Commands, actions and views can also post to it and update blocks.

Preview

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

Getting the room ​

WhereHow
An agentcontext.room. Read-only: agents change the room by yielding events.
A commandprops.room
A block actionblock.room, inside onAction
A room actionprops.room
A view, like a surface or inspector tabuseRoom(), which re-renders when the room changes

A plugin can only see the room it's working in. To read other rooms, such as for a dashboard, the manifest needs the rooms: "read" permission.

In the app today, only agents get the room. Posting to it from commands, actions and views is coming soon.

Room ​

PropertyTypeDescription
idstringStable for the life of the room
titlestringThe room's name
membersMember[]The people and agents in the room
messagesMessage[]The conversation, oldest first
statusRoomStatus"idle", "working", "needsYou", "stalled", "failed" or "offline"
answeringAnswering or undefinedWho answers a message that mentions no one, and the turn limit. See Rooms with several agents.

send ​

ts
function send(text: string): Promise<Message>

Posts a text message. Plugins post on behalf of the person who used them, and the message is labeled with your plugin's name, like "via Weather".

sendBlock ​

ts
function sendBlock<Payload>(options: {
  type: string
  payload: Payload
  fallbackText: string
}): Promise<Block<Payload>>

Posts a block, like a card. It's drawn by whichever plugin renders type, or shown as fallbackText if none does.

ts
await room.sendBlock({
  type: 'acme.weather',
  payload: weather,
  fallbackText: `${weather.city}: ${weather.temperature}°, ${weather.condition}`,
})

updateBlock ​

ts
function updateBlock<Payload>(id: string, payload: Payload): Promise<void>

Replaces the payload of a block your plugin posted. The block re-renders for everyone in the room. In a block's own action, use block.update(payload) instead.

data ​

ts
const data: {
  get<T>(key: string): Promise<T | undefined>
  set<T>(key: string, value: T): Promise<void>
  remove(key: string): Promise<void>
}

Small values your plugin saves on the room, like a setting for this room only. Each plugin has its own keys, invisible to other plugins. Values must be JSON. Keep them small: they're saved and synced with the room.

Member ​

PropertyTypeDescription
idstring
namestring
kind"person" or "agent"
isYoubooleanTrue for the person using the app
color"coral", "sun", "mint", "sky" or "grape"The member's color in the app
handlestring or undefinedWhat to write after @ to call this member, like Points for @Points. Defaults to the name. In the app it's the name without spaces, and a second member with the same name gets a number, like Scout2.
role"moderator", "member" or undefinedAgents only. A moderator answers messages that mention no one.
descriptionstring or undefinedOne line on what this agent is for, as other agents read it. In the app, the agent's "What it’s for" line.
pluginstring or undefinedThe plugin this agent comes from, so you can spot agents that share a backend with yours

An agent finds itself with context.self, not by searching this list.

Message ​

PropertyTypeDescription
idstring
authorMemberWho sent it
textstringThe plain text of the whole message, with each block's fallbackText in place of the block. Handy for sending to a model.
blocksBlock[]Everything in the message, in order
mentionsMember[]Members mentioned with @. In the person's message, they choose who answers. In an agent's reply, the app lists the members its hand-off lines handed off to; the SDK's test host lists every @Name in the reply.
viastring or undefinedThe plugin that posted it, if any
state"streaming", "complete", "interrupted" or "failed""interrupted" means the reply was stopped; "failed" means its agent threw an error
createdAtDate
handOff{ id: string; to: Member; callBack: boolean } or undefinedSet when this reply handed work to another member, with whether it asked for the result back. The first hand off, if the reply made several.

Block ​

PropertyTypeDescription
idstringStable, even when the payload changes
typestringLike "text", "code" or "acme.weather"
payloadPayloadThe block's data. JSON.
fallbackTextstringWhat people see without a plugin that draws type

Text is a block too: a message's text lives in blocks of type "text", with the payload { text }.

Surfaces that agents send with ui are blocks of type "a2ui", whose payload is the A2UI surface. Every block's saved snapshot is A2UI, whatever its type.

Rooms with several agents ​

A room can hold more than one agent. Three rules say who answers a message from the person: the agents it @mentions, anywhere in the message; with no mention, the room's moderator; with no moderator, every agent. Agents hand work to each other with handOff or with a line that starts with @Handle, can ask for the result back, and the room pauses after a set number of agent turns. The guide, Rooms with several agents, explains what the person sees and what an agent can do.

On the room, this shows up as answering, a handle, role, description and plugin on each Member, and handOff on a Message that handed work on. What an agent is told about its own turn is on AgentContext.

Answering ​

PropertyTypeDescription
moderatorsstring[]Member ids of the agents that answer a message that mentions no one. Empty means every agent answers. The app offers one moderator per room, and new rooms start with none.
turnLimitnumberThe most agent turns one message from the person can cause. 8 by default, from 1 to 32. The app has no setting for it yet, so its rooms use 8.
ts
const moderators = room.members.filter((m) => room.answering?.moderators.includes(m.id))

OtherRoom ​

Another room an agent is in, from AgentContext.otherRooms. It names the room and its agents and holds no messages: an agent that needs to know what was said there reads that room's history with its own tools, and only when it's relevant.

PropertyTypeDescription
idstringThe room's id, the same as room.id on a turn there.
titlestringThe room's name.
members{ id: string; name: string; handle?: string }[]The room's agents, this one included, in room order. The person is in every room, so isn't listed.
lastMessageAtDate or undefinedWhen the newest message was sent.

The privacy goes one way, and the app enforces it: it lists only rooms with two or more agents. From its DM, an agent hears about every room it shares with the person. A room never hears about a DM, or about a room of one agent and the person, because the other agents there would see whatever it brought in.

ts
const elsewhere = otherRooms.map((r) => `${r.title}, with ${r.members.filter((m) => m.id !== self.id).map((m) => m.name).join(', ')}`)

All your Agents, playing nicely in one Playground.