PraisonAIUI can host any AI agent backend behind a modular dashboard shell: pages, views, layout components, optional plugins, and branding — without forking the frontend.
Extension priority (first match wins):
1. window.aiui.registerView(pageId, …)
window.aiui.registerView(pageId, …)
2. Dashboard manifest plugins (dashboard-plugins/*/manifest.json)
dashboard-plugins/*/manifest.json
3. Built-in view modules (plugins/views/*.js via BUILTIN_VIEWS)
plugins/views/*.js
BUILTIN_VIEWS
4. Server aiui.layout() JSON from @aiui.page()
aiui.layout()
@aiui.page()
5. window.aiui.registerComponent(type, …) inside renderComponent
window.aiui.registerComponent(type, …)
renderComponent
6. Generic JSON fallback viewer
For YAML scene authoring with an external PraisonAI Video engine, see Video Studio.
See examples/python/external-agent-dashboard/app.py.
examples/python/external-agent-dashboard/app.py
| API | Purpose |
|-----|---------|
| version | Shell protocol version ('1') |
version
'1'
| registerView(pageId, renderFn, cleanup?) | Replace or add a full page renderer |
registerView(pageId, renderFn, cleanup?)
| registerComponent(type, renderFn) | Override a layout component type |
registerComponent(type, renderFn)
| registerSurfaceRenderer(surfaceId, renderFn) | Custom A2UI surface renderer |
registerSurfaceRenderer(surfaceId, renderFn)
| selectPage(pageId) | Navigate programmatically (e.g. open full canvas) |
selectPage(pageId)
| registerSlot(name, renderFn) | Inject DOM into named slots |
registerSlot(name, renderFn)
| sdk.fetchJSON(url, opts?) | Authenticated fetch helper |
sdk.fetchJSON(url, opts?)
| sdk.el(tag, attrs?, children?) | Small DOM builder |
sdk.el(tag, attrs?, children?)
| sdk.themeVar('--db-*', fallback?) | Read theme CSS variables |
sdk.themeVar('--db-*', fallback?)
| sdk.createBoard(root, { fetch, pollMs? }) | Live board with optional polling |
sdk.createBoard(root, { fetch, pollMs? })
| Slot id | Where it renders |
|---------|------------------|
| shell:sidebar:footer | Bottom of sidebar (default: health hint) |
shell:sidebar:footer
| page:{pageId}:toolbar | Right side of page header |
page:{pageId}:toolbar
Register only what you need; omit slots you do not use.
Define pages with @aiui.page() returning aiui.layout([...]). Types are implemented once in ui.py and dashboard.js.
aiui.layout([...])
ui.py
dashboard.js
Kanban / board: use aiui.board(columns=[...]). Columns contain id, title, and cards (from aiui.card() or dicts). The shell renders via renderBoard, composing existing card renderers (DRY).
aiui.board(columns=[...])
id
title
cards
aiui.card()
renderBoard
Three tiers work together:
| Tier | Mechanism | Use case |
|------|-----------|----------|
| Dashboard | aiui.layout() → _components | Python-authored pages |
_components
| A2UI | send_a2ui_messages → SurfaceHost | Agent-generated UI in chat/canvas |
send_a2ui_messages
SurfaceHost
| AG-UI | POST /agui SSE | CopilotKit / external clients |
POST /agui
Register an empty canvas page:
Or use @aiui.surface_action("main") for button callbacks.
@aiui.surface_action("main")
Full guide: A2UI canvas — chat-canvas split view, send_a2ui_messages, HTTP/CLI, coerce_a2ui_tool_messages, troubleshooting. Example: examples/python/30-a2ui-canvas/.
coerce_a2ui_tool_messages
examples/python/30-a2ui-canvas/
Load heavy built-ins only when listed:
This adds jobs.js, auth.js, or api.js to the plugin chain and maps them in BUILTIN_VIEWS. feedback is always available as a built-in view when the page is enabled.
jobs.js
auth.js
api.js
feedback
Place folders under:
~/.praisonai/dashboard-plugins/{name}/
src/praisonaiui/templates/frontend/dashboard-plugins/{name}/
Each plugin needs manifest.json + index.js (optional styles.css):
manifest.json
index.js
styles.css
The server exposes:
GET /api/dashboard/plugins
GET /dashboard-plugins/{name}/{path}
Plugins register views in index.js:
Sample: sample-board.
sample-board
| System | Location | Purpose |
|--------|----------|---------|
| Agent plugins | ~/.praisonai/plugins/ | Python agent extensions |
~/.praisonai/plugins/
| Dashboard plugins | ~/.praisonai/dashboard-plugins/ | JS UI tabs |
~/.praisonai/dashboard-plugins/
See PraisonAI package integration for backend wiring, jobs API, and deployment.
| What you control | How | Example |
|------------------|-----|---------|
| UI mode | aiui.set_style(...) | "dashboard", "chat", "docs" |
aiui.set_style(...)
"dashboard"
"chat"
"docs"
| Sidebar pages | aiui.set_pages([ids]) whitelist | ["chat", "sessions"] |
aiui.set_pages([ids])
["chat", "sessions"]
| Hide built-ins | YAML pages.disabled: [...] | Blacklist in server |
pages.disabled: [...]
| Sidebar on/off | set_dashboard(sidebar=False) | Chat-only full width |
set_dashboard(sidebar=False)
| Page title bar | set_dashboard(page_header=False) | Cleaner surface |
set_dashboard(page_header=False)
| Optional modules | set_dashboard(modules=[...]) | ["jobs"] only |
set_dashboard(modules=[...])
["jobs"]
| Third-party tabs | Install chosen dashboard-plugins/ folders | Manifest per plugin |
dashboard-plugins/
| Shell chrome | registerSlot | Header/footer widgets |
registerSlot
| Look only | set_theme, set_branding, set_custom_css | White-label |
set_theme
set_branding
set_custom_css
| Replace one page | registerView(pageId, ...) | Override built-in |
registerView(pageId, ...)
| Board UI | aiui.board() or plugin | Not in default nav |
aiui.board()
Note: @aiui.page() custom pages are not filtered by set_pages() — only built-in dashboard pages are. Remove custom pages from code to hide them.
set_pages()
CLI: aiui pages ids lists built-in page ids for whitelists.
aiui pages ids
1. Add new layout types in ui.py and one case in dashboard.js.
case
2. Page-specific UI belongs in **plugins/views/*.js**, delegating to shared modules (jobs.js, etc.) via thin wrappers.
3. Reuse _helpers.js (pageToolbar, filterChips, searchInput, modalShell, toast).
_helpers.js
pageToolbar
filterChips
searchInput
modalShell
toast
4. Boards compose card / columns — do not duplicate card markup in plugins.
card
columns
| File | Role |
|------|------|
| praisonai-package-integration.md | Praison backend wiring |
praisonai-package-integration.md
| server.py | Pages API, set_dashboard, plugin chain |
server.py
set_dashboard
| dashboard_plugins.py | Manifest discovery and static routes |
dashboard_plugins.py
| dashboard.js | Shell, registries, renderers |
| schema/models.py | DashboardConfig.modules, plugin_dirs |
schema/models.py
DashboardConfig.modules
plugin_dirs