|
| 1 | +# @agents-ui |
| 2 | + |
| 3 | +Agents UI is the easiest way to build agentic voice applications faster on top of LiveKit primitives. |
| 4 | + |
| 5 | +Agents UI is a component library built on top of [shadcn/ui](https://ui.shadcn.com/) and [AI Elements](https://ai-sdk.dev/elements) to accelerate building agentic applications on top of LiveKit's real-time platform. It provides pre-built components like controling IO, managing sessions, rendering transcripts, visualing audio streams, and more. |
| 6 | + |
| 7 | +## Components |
| 8 | + |
| 9 | +### Agent UI Components |
| 10 | + |
| 11 | +Located in `components/agents-ui/`, these are the primary components for building agent interfaces: |
| 12 | + |
| 13 | +| Component | Description | |
| 14 | +| ---------------------------- | --------------------------------------------------------------------------------------- | |
| 15 | +| `AgentSessionProvider` | Wraps your agent UI, providing session context and audio rendering | |
| 16 | +| `AgentControlBar` | Full-featured control bar with mic, camera, screen share, chat, and disconnect controls | |
| 17 | +| `AgentTrackToggle` | Toggle button for media tracks (microphone, camera, screen share) | |
| 18 | +| `AgentTrackControl` | Media control with device selector dropdown | |
| 19 | +| `AgentDisconnectButton` | Button to end the agent session | |
| 20 | +| `AgentChatTranscript` | Displays the conversation transcript including voice transcriptions | |
| 21 | +| `AgentChatIndicator` | Visual indicator for agent thinking/processing state | |
| 22 | +| `AgentAudioVisualizerBar` | Linear bar audio visualizer | |
| 23 | +| `AgentAudioVisualizerGrid` | Grid-based audio visualizer | |
| 24 | +| `AgentAudioVisualizerRadial` | Radial/circular audio visualizer | |
| 25 | +| `StartAudioButton` | Button to start audio when browser blocks autoplay | |
| 26 | + |
| 27 | +## Prerequisites |
| 28 | + |
| 29 | +Before installing AI Elements, make sure your environment meets the following requirements: |
| 30 | + |
| 31 | +- [Node.js](https://nodejs.org/), version 18 or later |
| 32 | +- [shadcn/ui](https://ui.shadcn.com/docs/installation/nextjs) is installed in your project. |
| 33 | + |
| 34 | +> [!NOTE] |
| 35 | +> Running any install command will automatically install shadcn/ui for you. |
| 36 | +> Agents UI is built targeting React 19 (no forwardRef usage) and Tailwind CSS 4. |
| 37 | +
|
| 38 | +## Installation |
| 39 | + |
| 40 | +You can install Agents UI components using the shadcn/ui CLI. |
| 41 | + |
| 42 | +First add the Agents UI registry to your components.json file: |
| 43 | + |
| 44 | +```json |
| 45 | +{ |
| 46 | + ... |
| 47 | + "registries": { |
| 48 | + ... |
| 49 | + "@agents-ui": "https://livekit.io/ui/r/{name}.json" |
| 50 | + } |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +Then install the component you want to use from the CLI. Ensure you've navigated to the root of your project. |
| 55 | + |
| 56 | +```bash |
| 57 | +npx shadcn@latest add @agents-ui/{component-name} |
| 58 | +``` |
| 59 | + |
| 60 | +## Usage |
| 61 | + |
| 62 | +Most Agents UI components require access to a LiveKit session object for access to values like agent state or audio tracks. The session object can be created from a [TokenSource](/reference/client-sdk-js/variables/TokenSource.html), and provided by wrapping the component in an [AgentSessionProvider](../component/agent-session-provider/page.mdoc). |
| 63 | + |
| 64 | +```tsx |
| 65 | +'use client'; |
| 66 | + |
| 67 | +import { useSession } from '@livekit/components-react'; |
| 68 | +import { AgentSessionProvider } from '@/components/agents-ui/agent-session-provider'; |
| 69 | +import { AgentControlBar } from '@/components/agents-ui/agent-control-bar'; |
| 70 | + |
| 71 | +const TOKEN_SOURCE = TokenSource.sandboxTokenServer(process.env.MY_LK_SANDBOX_TOKEN_SERVER_ID); |
| 72 | + |
| 73 | +export function Demo() { |
| 74 | + const session = useSession(TOKEN_SOURCE); |
| 75 | + |
| 76 | + return ( |
| 77 | + <AgentSessionProvider session={session}> |
| 78 | + <AgentControlBar |
| 79 | + variant={{ variant }} |
| 80 | + isChatOpen={{ isChatOpen }} |
| 81 | + isConnected={{ isConnected }} |
| 82 | + controls={{ controls }} |
| 83 | + /> |
| 84 | + </AgentSessionProvider> |
| 85 | + ); |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +## Extensibility |
| 90 | + |
| 91 | +Agents UI components take as many primitive attributes as possible. For example, the [AgentControlBar](/reference/components/shadcn/component/agent-control-bar/page.mdoc) component extends `HTMLAttributes<HTMLDivElement>`, so you can pass any props that a div supports. This makes it easy to extend the component with your own styles or functionality. |
| 92 | + |
| 93 | +You can edit any Agents UI component's source code in the `components/agents-ui` directory. For style changes, we recommend passing in tailwind classes to override the default styles. Take a look at the source code to get a sense of how to override component's default styles. |
| 94 | + |
| 95 | +If you re-install any Agents UI component by rerunning `npx shadcn@latest add @agents-ui/{component-name}`, the CLI will ask before overwriting the file so you can save any custom changes you made. |
| 96 | + |
| 97 | +After installation, no additional setup is needed. The component's styles (Tailwind CSS classes) and scripts are already integrated. You can start interacting with the component in your app immediately. |
| 98 | + |
| 99 | +## Architecture |
| 100 | + |
| 101 | +``` |
| 102 | +packages/shadcn/ |
| 103 | +├── components/ |
| 104 | +│ ├── agents-ui/ # LiveKit agent-specific components |
| 105 | +│ ├── ai-elements/ # Reusable AI conversation components |
| 106 | +│ ├── ui/ # Base UI primitives (shadcn/ui style) |
| 107 | +│ └── session-provider.tsx |
| 108 | +├── hooks/ |
| 109 | +│ └── agents-ui/ # Custom hooks for agent UI logic |
| 110 | +├── lib/ |
| 111 | +│ └── utils.ts # Utility functions (cn, etc.) |
| 112 | +├── scripts/ |
| 113 | +│ ├── doc-gen.ts # Generates prop documentation |
| 114 | +│ └── update.ts # Deploys registry to destination |
| 115 | +├── registry.json # shadcn registry configuration |
| 116 | +└── index.ts # Package exports |
| 117 | +``` |
| 118 | + |
| 119 | +### Key Architectural Decisions |
| 120 | + |
| 121 | +1. **shadcn Registry Distribution**: Components are distributed via shadcn's registry system rather than as a traditional npm package. This allows users to copy components directly into their codebase and customize them freely. |
| 122 | + |
| 123 | +2. **Tailwind CSS Styling**: All components use Tailwind CSS with the `class-variance-authority` (CVA) pattern for variant management, following shadcn/ui conventions. |
| 124 | + |
| 125 | +3. **Radix UI Primitives**: Base UI components are built on [Radix UI](https://www.radix-ui.com/) primitives for accessibility and behavior. |
| 126 | + |
| 127 | +4. **LiveKit Integration**: Agent components integrate with `@livekit/components-react` hooks and context providers for real-time communication features. |
| 128 | + |
| 129 | +5. **Motion Animations**: Animations are powered by [Motion](https://motion.dev/) (formerly Framer Motion) for smooth, performant transitions. |
| 130 | + |
| 131 | +## Development |
| 132 | + |
| 133 | +### Preview |
| 134 | + |
| 135 | +Preview the components in storybook by running from the root of the monorepo: |
| 136 | + |
| 137 | +```bash |
| 138 | +pnpm dev:storybook |
| 139 | +``` |
| 140 | + |
| 141 | +You can find the components in [Storybook](http://localhost:6006) under the `Agents UI` section. |
| 142 | + |
| 143 | +### Scripts |
| 144 | + |
| 145 | +```bash |
| 146 | +# Build the shadcn registry |
| 147 | +pnpm registry:build |
| 148 | + |
| 149 | +# Serve the registry locally (http://localhost:3210) |
| 150 | +pnpm registry:serve |
| 151 | + |
| 152 | +# Generate prop documentation |
| 153 | +pnpm registry:doc-gen |
| 154 | + |
| 155 | +# Build and deploy to configured destination paths |
| 156 | +pnpm registry:update |
| 157 | +``` |
| 158 | + |
| 159 | +### Environment Variables |
| 160 | + |
| 161 | +Create a `.env.local` file with: |
| 162 | + |
| 163 | +```env |
| 164 | +# Path to deploy built registry files |
| 165 | +DEST_REGISTRY_PATH=/path/to/destination/registry |
| 166 | +
|
| 167 | +# Path to deploy generated prop types documentation |
| 168 | +DEST_PROP_TYPES_PATH=/path/to/destination/prop-types.json |
| 169 | +``` |
| 170 | + |
| 171 | +## Dependencies |
| 172 | + |
| 173 | +### Peer Dependencies |
| 174 | + |
| 175 | +- `@livekit/components-react` - LiveKit React components |
| 176 | +- `livekit-client` - LiveKit client SDK |
| 177 | +- `react` ^19.0.0 |
| 178 | +- `react-dom` ^19.0.0 |
| 179 | + |
| 180 | +## Reporting issues |
| 181 | + |
| 182 | +Please file issues in the [GitHub repository](https://github.com/livekit/components-js/issues). |
0 commit comments