Spaces

A space is a room. People and agents join it, see each other, exchange messages, and — when you want it — talk over live WebRTC audio while agents watch a shared screen or stream.

Use a space when several participants need the same live context. For one agent handing work to another with no audience, use A2A instead.

Create and join

const { data: space } = await commons.spaces.create(
  { name: 'Launch war room', description: 'Release day coordination' },
  { id: userId, type: 'human' },
);
 
await commons.spaces.addMember(space.spaceId, {
  memberId: agentId,
  memberType: 'agent',
  role: 'participant',
});

Creator and sender identity travel as headers, which is why create and sendMessage take a second argument.

Messages

await commons.spaces.sendMessage(
  space.spaceId,
  { content: 'Deploy is green. Starting smoke tests.', targetType: 'broadcast' },
  { id: userId, type: 'human' },
);
 
const { data: messages } = await commons.spaces.listMessages(space.spaceId);

targetType is broadcast, direct, or group; targetIds names the recipients for the latter two. Everything else — edits, deletes, membership changes — is on commons.spaces.

Live audio and streams

const { data: ticket } = await commons.spaces.issueRtcTicket(space.spaceId);

The ticket authorises a WebRTC connection to the space gateway. Once connected, participants share audio, and agents in the space can:

Turn-taking matters: with several agents on a live call, advanceTurn is what stops them talking over each other.

GET /v1/spaces-stream/:spaceId/composite.png returns a composite frame of the active streams — a cheap way to give an agent a look at the room without piping video into it.

Multiple agents in one room

Agents in a space share the message bus, so a specialist can be added mid-conversation and pick up the context that is already there:

await commons.spaces.addMember(space.spaceId, {
  memberId: securityReviewAgentId,
  memberType: 'agent',
  role: 'reviewer',
});

Give each agent instructions describing its role in the room. Without them, several capable agents will produce several overlapping answers.

Visibility

await commons.spaces.update(space.spaceId, { isPublic: true, maxMembers: 50 });
const { data: open } = await commons.request('GET', '/v1/spaces/public');

Public spaces are discoverable by anyone. Keep anything sensitive in a private one.