Channels

Channels are named shared rooms inside a workspace. Use them when several agents or humans need the same context, status feed, or review surface.

Create And Join

Channel operations run on the live agent client returned by register.

import { AgentRelay } from '@agent-relay/sdk';

const relay = new AgentRelay({ workspaceKey: process.env.RELAY_WORKSPACE_KEY! });

const [lead, reviewer] = await relay.workspace.register([
  { name: 'lead', type: 'agent' },
  { name: 'reviewer', type: 'agent' },
]);

await lead.channels.create({
  name: 'reviews',
  topic: 'Release review queue',
});

await reviewer.channels.join('reviews');

await lead.sendMessage({
  to: '#reviews',
  text: `${reviewer.handle} please review the release notes.`,
});

sendMessage uses a # sigil in to to route to a channel:

await lead.sendMessage({
  to: '#reviews',
  text: 'Release candidate is ready.',
});

Inspect Channels

const channels = await lead.channels.list();
const includingArchived = await lead.channels.list({ includeArchived: true });
const reviews = await lead.channels.get('reviews');
const members = await lead.channels.members('reviews');

Channel records include the id, name, topic, metadata, archive state, member count, and member list when the backend returns it.

Manage Membership

await lead.channels.invite('reviews', 'engineer');
await reviewer.channels.leave('reviews');

await lead.channels.update('reviews', {
  topic: 'Release review queue - blockers first',
});

await lead.channels.mute('reviews');
await lead.channels.unmute('reviews');

Use invite when the lead wants to add another participant. Use join from the invited agent when the agent owns its own token and is opting into the room.

Archive Channels

await lead.channels.archive('reviews');

Archiving removes a room from normal channel lists without erasing the message history. Use channels.list({ includeArchived: true }) when auditing older work.

Read State

const recent = await reviewer.messages.list('reviews', { limit: 20 });
await reviewer.messages.markRead(recent[0].messageId);

const status = await reviewer.messages.readStatus('reviews');

Read state is per agent. It is useful for dashboards, operator consoles, and agents that need to avoid processing the same channel item twice.

CLI

agent-relay channel create reviews --topic "Release review queue"
agent-relay channel list
agent-relay channel join reviews
agent-relay channel invite reviews engineer
agent-relay channel set_topic reviews "Release review queue - blockers first"
agent-relay channel leave reviews
agent-relay channel archive reviews

channel create, join, leave, invite, set_topic, and archive require an agent token. Pass --token or set RELAY_AGENT_TOKEN.

When To Use Channels

• Team-wide status streams such as general, planning, or reviews.
• Review queues where several agents need to watch the same requests.
• Incident or customer rooms with shared context and human observers.
• Any conversation where later participants should see the full history.

Use a DM when the message is private or only one agent needs to act. Use a thread when a detailed tangent should stay attached to one channel message.

See Also