Web Component API

<rtc-agent> is the sole component exposed by RTC Agent. Built on Lit, it contains 38 sub-components and 20 Controllers internally, but presents only a clean Web Component interface externally — attribute configuration, event listening, and CSS variable customization.

Attributes

Attribute	Type	Default	Description
🎨 theme	"light" | "dark" | "system"	"system"	Theme mode. system follows the OS setting
📛 app-label	string	"RTC Agent"	Title bar text + minimized bubble tooltip
🖼️ bubble-icon	string	Default icon	SVG / HTML content displayed inside the minimized bubble
📄 scenarios-url	string	—	URL of the scenario manifest, pointing to manifest.json
🔗 server-url	string	""	Server address. Falls back to the current page’s domain when empty

JS Properties (set via JavaScript only, not HTML attributes):

Property	Type	Default	Description
⚙️ agentConfig	object	null	Declarative function registration (recommended approach)
📦 registry	FunctionRegistry	null	Imperative function registration (created via defineRegistry)
🪟 windowConfig	WindowConfig	null	Window behavior configuration (mode, size, interaction limits)
🎛️ activityBarConfig	ActivityBarConfig	null	Activity Bar button visibility configuration

Quick Integration

<!-- Minimal integration -->
<rtc-agent></rtc-agent>

<!-- Custom theme and title -->
<rtc-agent theme="dark" app-label="My AI Assistant"></rtc-agent>

<!-- With scenario docs and function registration -->
<rtc-agent
  app-label="Order Assistant"
  scenarios-url="https://example.com/scenarios"
  .agentConfig=${{
    name: 'OrderApp',
    persona: 'You are an order management assistant',
    groups: [{ /* ... */ }]
  }}
></rtc-agent>

// Window configuration (JS property, set after rtc-agent-ready)
const agent = document.querySelector('rtc-agent');

agent.addEventListener('rtc-agent-ready', () => {
  // Embedded panel: disable drag/resize/buttons, default to maximized
  agent.windowConfig = { embedded: true };

  // Keep only chat, hide files/settings buttons
  agent.activityBarConfig = {
    disabledActivities: ['files', 'settings'],
  };
});

Events

Event	Trigger	Purpose
🟢 rtc-agent-ready	Component initialization complete	Safe to access the component instance and set attributes at this point

const agent = document.querySelector('rtc-agent');

agent.addEventListener('rtc-agent-ready', () => {
  // Component is ready, safe to operate
  agent.theme = 'dark';
  agent.appLabel = 'Custom Title';
});

💡 Best Practice: Always wait for the rtc-agent-ready event before interacting with the component to avoid errors caused by uninitialized state.

Window System

<rtc-agent> includes three built-in window modes, supporting floating, fullscreen, and minimized bubble:

Interaction	Description
🖱️ Drag	The title bar serves as the drag handle
↔️ Resize	Supports 8-directional resize operations
⌨️ Keyboard	Arrow keys move the window; Shift to accelerate
📏 Viewport constraint	Window always stays within the visible area and cannot be dragged off-screen

Window Configuration

Use the windowConfig property to control default window behavior and interaction limits:

agent.windowConfig = {
  // Default window mode
  defaultMode: 'maximized',  // 'normal' | 'maximized' | 'minimized'

  // Embedded mode (shortcut)
  // Equivalent to: defaultMode: 'maximized' + draggable: false + resizable: false
  //                + showMinimize: false + showMaximize: false
  embedded: true,

  // Fine-grained control
  draggable: false,       // Whether the window can be dragged
  resizable: false,       // Whether the window can be resized
  showMinimize: false,    // Whether to show the minimize button
  showMaximize: false,    // Whether to show the maximize button
  showClose: false,       // Whether to show the close button

  // Size and position
  initialSize: { width: 420, height: 640 },
  initialPosition: { x: 100, y: 100 },
  minWidth: 350,
  minHeight: 520,
  maxWidth: Infinity,
  maxHeight: Infinity,

  // Minimized bubble position
  bubblePosition: {
    corner: 'bottom-right',  // Origin corner of the coordinate system
    offset: { x: -20, y: 20 },  // Cartesian coordinate offset
  },
};

Bubble Position Configuration

bubblePosition uses a mathematical Cartesian coordinate system to control the position of the minimized bubble:

Field	Type	Description
corner	'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'	The corner of the host application where the coordinate origin is placed
offset.x	number	Horizontal offset (positive = right, negative = left)
offset.y	number	Vertical offset (positive = up, negative = down, mathematical coordinate system)

Examples:

// Bottom-right corner, 20px inward offset (default)
bubblePosition: { corner: 'bottom-right', offset: { x: -20, y: 20 } }

// Top-left corner, 20px offset to bottom-right
bubblePosition: { corner: 'top-left', offset: { x: 20, y: -20 } }

// Bottom-left corner, 30px offset to top-right
bubblePosition: { corner: 'bottom-left', offset: { x: 30, y: 30 } }

💡 Expand Direction: On the first restore from minimized state, the window expands based on the corner configuration. For example, with corner: 'bottom-right', the window’s bottom-right corner aligns with the bubble position, expanding toward the upper-left. Subsequent minimize/restore cycles use the remembered position.

Common Scenarios:

Scenario	Configuration
Embedded panel	{ embedded: true }
Fixed position window	{ draggable: false, resizable: false }
No minimize button	{ showMinimize: false, defaultMode: 'maximized' }
Floating chat window	null (uses defaults)

Activity Bar Configuration

Use the activityBarConfig property to control button visibility in the Activity Bar:

agent.activityBarConfig = {
  // Activities to hide (chat is always visible and cannot be hidden)
  disabledActivities: ['files', 'settings'],

  // Default active activity
  defaultActivity: 'chat',  // 'chat' | 'files' | 'settings'
};

Activity	Description	Hideable
💬 chat	Chat interface	❌ Always visible
📁 files	File manager	✅
⚙️ settings	Settings panel	✅

State Management

The component uses 20 Controllers internally to manage state. 9 core state Controllers handle business logic, and 11 UI Controllers handle interface interactions. Controllers do not reference each other directly; instead, the root component <rtc-agent> acts as the central hub orchestrating cross-Controller communication:

💡 Design Principle: Controllers are decoupled from each other; all cross-Controller communication goes through the root component. Sub-components obtain state via @lit/context and do not hold direct Controller references.

CSS Variables

CSS variables allow you to customize the component’s appearance and dimensions without modifying source code:

rtc-agent {
  /* Window default dimensions */
  --rtc-window-default-width: 420px;
  --rtc-window-default-height: 640px;

  /* Minimized bubble size */
  --rtc-bubble-size: 40px;
}

Variable	Default	Description
--rtc-window-default-width	420px	Default width of the floating window
--rtc-window-default-height	640px	Default height of the floating window
--rtc-bubble-size	40px	Diameter of the minimized bubble

Style System

The component uses a three-layer style architecture, progressing from foundational tokens to top-level variables:

Layer	Content	Description
🏗️ Design Tokens	Spacing, typography, radius, shadow, transition, z-index	Foundational design constants ensuring visual consistency
🌓 Color Themes	Light / Dark (VS Code style)	Two complete color schemes with automatic adaptation
🔧 CSS Variables	Component-level customization (window dimensions, bubble size)	Overridable by host applications for personalization

Key Interactions

Area	Behavior
⌨️ Input Area	Textarea + bottom toolbar; Enter to submit, Shift+Enter for newline; toolbar includes attachments, tools, mode toggle, send/stop
📨 Message List	Auto-scrolls to bottom; “New messages” button shown when user scrolls away; supports Markdown rendering and code highlighting
⚡ Tool Confirmation Dialog	Displays tool name and parameters; Yes / No buttons; clicking the background is equivalent to rejecting

Next Steps

• Authentication & Authorization — Learn about the login flow and token mechanism
• Function Registration Guide — Register custom functions via agentConfig
• Scenario Authoring Guide — Write scenario documents to guide AI behavior