Appearance
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
| Where | How |
|---|---|
| An agent | context.room. Read-only: agents change the room by yielding events. |
| A command | props.room |
| A block action | block.room, inside onAction |
| A room action | props.room |
| A view, like a surface or inspector tab | useRoom(), 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
| Property | Type | Description |
|---|---|---|
id | string | Stable for the life of the room |
title | string | The room's name |
members | Member[] | The people and agents in the room |
messages | Message[] | The conversation, oldest first |
status | RoomStatus | "idle", "working", "needsYou", "stalled", "failed" or "offline" |
answering | Answering or undefined | Who 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
| Property | Type | Description |
|---|---|---|
id | string | |
name | string | |
kind | "person" or "agent" | |
isYou | boolean | True for the person using the app |
color | "coral", "sun", "mint", "sky" or "grape" | The member's color in the app |
handle | string or undefined | What 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 undefined | Agents only. A moderator answers messages that mention no one. |
description | string or undefined | One line on what this agent is for, as other agents read it. In the app, the agent's "What it’s for" line. |
plugin | string or undefined | The 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
| Property | Type | Description |
|---|---|---|
id | string | |
author | Member | Who sent it |
text | string | The plain text of the whole message, with each block's fallbackText in place of the block. Handy for sending to a model. |
blocks | Block[] | Everything in the message, in order |
mentions | Member[] | 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. |
via | string or undefined | The 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 |
createdAt | Date | |
handOff | { id: string; to: Member; callBack: boolean } or undefined | Set 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
| Property | Type | Description |
|---|---|---|
id | string | Stable, even when the payload changes |
type | string | Like "text", "code" or "acme.weather" |
payload | Payload | The block's data. JSON. |
fallbackText | string | What 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
| Property | Type | Description |
|---|---|---|
moderators | string[] | 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. |
turnLimit | number | The 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.
| Property | Type | Description |
|---|---|---|
id | string | The room's id, the same as room.id on a turn there. |
title | string | The 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. |
lastMessageAt | Date or undefined | When 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(', ')}`)