appointment
Tue 14 Jun · 3:30 PM
Dr. Lewis · 30 min checkup
confirmed
Ship a demo
A demo is a small voice agent in the awesome-voice-apps cookbook. The agent runs on the contributor's machine; this playground is the browser client that talks to it and renders its UI. Here is the whole path.
01
Scope your demo
Pick one concrete task an agent can do by voice (book a slot, take an order, quiz the caller). Decide which of the components below it will draw, so you build against what already exists.
02
Fork and branch
Fork the cookbook and branch off
main:git switch -c feat/demo-<slug>03
Write the agent
Copy To draw UI, publish
templates/livekit-base/ into demos/<slug>/, edit agent.py and pyproject.toml, and run it locally:uv run python agent.py devui_event envelopes on the ui data channel and list the component names in your playground.json.04
Reuse a component
These render in the agent canvas already. Use a name below and send its props in a
ui_event; expand a tile to copy the exact envelope. They are available to every demo, no playground change needed.List
titled rows with subtitle, badge, image, link
- $4.50
Flat white
oat milk · large
- $3.75
Almond croissant
{
"type": "ui_event",
"component": "List",
"action": "mount",
"props": {
"items": [
{
"title": "Flat white",
"subtitle": "oat milk · large",
"right": "$4.50"
},
{
"title": "Almond croissant",
"right": "$3.75"
}
]
}
}items: { title, subtitle?, right?, image_url?, href? }[]title?: string
KeyValue
label/value rows, last one emphasized
- subtotal
- $8.25
- tax
- $0.74
- total
- $8.99
{
"type": "ui_event",
"component": "KeyValue",
"action": "mount",
"props": {
"items": [
{
"label": "subtotal",
"value": "$8.25"
},
{
"label": "tax",
"value": "$0.74"
},
{
"label": "total",
"value": "$8.99",
"accent": true
}
]
}
}items: { label, value, accent? }[]title?: string
Stat
big number with label and progress bar
open slots
7/ 10
{
"type": "ui_event",
"component": "Stat",
"action": "mount",
"props": {
"value": 7,
"label": "open slots",
"of": 10
}
}value: string | numberlabel?: stringof?: numbercaption?: string
Meters
labeled 0-to-1 bars with band coloring and a driver mark
audio health
noisedriver0.72
reverb0.18
loudnesslevel0.55
{
"type": "ui_event",
"component": "Meters",
"action": "mount",
"props": {
"title": "audio health",
"items": [
{
"label": "noise",
"value": 0.72,
"band": "bad",
"driver": true
},
{
"label": "reverb",
"value": 0.18,
"band": "good"
},
{
"label": "loudness",
"value": 0.55,
"neutral": true
}
]
}
}items: { label, value: number (0..1), band?: "good"|"warn"|"bad", neutral?: boolean, driver?: boolean }[]title?: string
Card
article: subtitle, title, body, footer
{
"type": "ui_event",
"component": "Card",
"action": "mount",
"props": {
"subtitle": "appointment",
"title": "Tue 14 Jun · 3:30 PM",
"body": "Dr. Lewis · 30 min checkup",
"footer": "confirmed",
"accent": true
}
}title?: stringsubtitle?: stringbody?: stringimage_url?: stringfooter?: stringaccent?: boolean
Buttons
button row; emits a CTA event on click
{
"type": "ui_event",
"component": "Buttons",
"action": "mount",
"props": {
"buttons": [
{
"label": "Confirm order",
"action": "confirm",
"primary": true
},
{
"label": "Add a note",
"action": "note"
}
]
}
}buttons: { label, href?, action?, primary? }[]title?: string
05
Write the blog (required)
Every demo ships a short build writeup at
demos/<slug>/blog.md and sets "blog": true in playground.json. Plain markdown only (no raw HTML, no em dashes). To add an image or diagram, host it at a public internet URL and link it inline, like . Image files are not committed to the repo, and inline <svg> or HTML is stripped, so the URL must be publicly fetchable. Start from this:--- title: <one line on what you built> summary: <one or two sentences; becomes the page description> author: <your name> --- ## The problem What real task this agent does. ## Why this stack The STT, LLM, and TTS you picked, one reason each. ## The interesting part The 20-40 lines that make it work. ## What surprised me One thing you learned building it. ## Run it https://playground.mahimai.ca/demos/<slug>
See a finished one: front-desk-interpreter/blog.md ↗
06
Open the PR
Commit
feat(demo): <slug> and open a PR. The cookbook's pre-commit hook regenerates catalog.json (never edit it by hand). Once merged, your demo appears on the playground within about five minutes. Full rules: cookbook CONTRIBUTING ↗.