Data channel topics

Topics are defined in @scenaro/sdk/protocol and shared between the Python voice agent and all frontends. They travel over the Transport data channel — LiveKit’s data channel today.

import { DATA_TOPICS, toolDataTopic } from '@scenaro/sdk/protocol';

Topic table

Topic	Direction	Role
`config`	agent → front	Handshake: features, collections, restore state
`config_ack`	front → agent	Acknowledge config received
`config_request`	agent → front	Request config resend
`message:new`	agent → front	Conversation message (user/assistant/tool/event)
`session:end`	agent → front	Agent-initiated session end
`dictation:transcript`	agent → front	Real-time STT transcript
`state:update`	front → agent	Experience state checkpoint
`ui:activity`	front → agent	UI activity heartbeat
`assistant:interrupt`	front → agent	Interrupt assistant speech
`session:control`	bidirectional	Session control signals
`event:fire`	bidirectional	Custom event firing
`lk.chat`	front → agent	User text message
`tool:{toolName}`	dynamic	Tool response channel via `toolDataTopic()`

Source definition

export const DATA_TOPICS = {
  CONFIG: 'config',
  CONFIG_ACK: 'config_ack',
  CONFIG_REQUEST: 'config_request',
  MESSAGE_NEW: 'message:new',
  SESSION_END: 'session:end',
  DICTATION_TRANSCRIPT: 'dictation:transcript',
  EVENT_FIRE: 'event:fire',
  STATE_UPDATE: 'state:update',
  SESSION_CONTROL: 'session:control',
  ASSISTANT_INTERRUPT: 'assistant:interrupt',
  UI_ACTIVITY: 'ui:activity',
  CHAT: 'lk.chat',
} as const;

Dynamic tool topics

toolDataTopic('search_collection_items'); // → 'tool:search_collection_items'

Handshake sequence

Agent sends config

Agent publishes on config with features, collections, and optional restore_state.

Frontend processes

The SDK session dispatches the payload on the event bus; FeatureProvider registers features and RPC methods.

Frontend acks

Frontend sends config_ack with { acknowledged: true, timestamp }.

Versioning

The protocol package has zero dependencies and serves as the cross-language spec. Future Python/Go SDKs will align on this same topic and message definitions. Potential future extraction: standalone scenaro-protocol npm/PyPI package.

​Topic table

​Source definition

​Dynamic tool topics

​Handshake sequence

​Versioning

​See also

Topic table

Source definition

Dynamic tool topics

Handshake sequence

Versioning

See also