UI Presets

Bootstrap a chat/dashboard/bot UI in 3 lines using a preset

UIPreset packages every UI knob into one object so build_ui_app(preset) returns a ready-to-serve app.

from praisonaiagents import Agent
from praisonai.integration.host_app import UIPreset, build_ui_app

agent = Agent(name="Helper", instructions="Be concise.")
preset = UIPreset(
    title="My Bot",
    agent_kwargs={"name": "Helper", "instructions": "Be concise."},
)
app = build_ui_app(preset)
agent.start("Hello from the preset UI")

The user opens the preset UI and chats; build_ui_app serves the configured agent instantly.

Quick Start

1. Chat UI in three lines

   Start with an agent, wire it through agent_kwargs, and serve:

   from praisonaiagents import Agent
   from praisonai.integration.host_app import UIPreset, build_ui_app
   
   preset = UIPreset(
       title="My Bot",
       agent_kwargs={
           "name": "Helper",
           "instructions": "Be concise.",
       },
   )
   app = build_ui_app(preset)
   # uvicorn main:app --host 0.0.0.0 --port 8000
   
2. Custom agent factory

   Use agent_factory when each session needs a fresh agent:

   from praisonaiagents import Agent
   from praisonai.integration.host_app import UIPreset, build_ui_app
   
   def make_agent(settings):
       return Agent(
           name="Helper",
           instructions="Be concise.",
           llm=settings.get("model", "gpt-4o-mini"),
       )
   
   preset = UIPreset(title="Dynamic Bot", agent_factory=make_agent)
   app = build_ui_app(preset)
   

---

UIPreset Fields

Field	Type	Default	Description
title	str	"PraisonAI"	Browser tab and header title
logo	str	"🤖"	Logo emoji or text in the sidebar
pages	List[str]	["chat"]	Enabled UI pages (chat, agents, sessions, …)
theme	Dict	blue preset, dark mode	Theme dict passed to configure_host
agent_kwargs	Dict	{}	Keyword args for default Agent(...)
starters	List[Dict]	[]	Conversation starter chips
welcome	str	greeting message	Shown on first load via @aiui.welcome
sidebar	bool	True	Show sidebar navigation
page_header	bool	True	Show page header bar
openai_fallback	bool	False	Fall back to OpenAI when agent errors (legacy mode)
settings_handler	Callable | None	None	Async (new_settings) -> None on settings change
agent_factory	Callable | None	None	(settings) -> Agent for per-session agents
realtime_manager	Any | None	None	OpenAI realtime manager instance
agent_loader	Callable | None	None	Load agents from YAML at startup

---

Default App Patterns

All five bundled UI apps now use build_ui_app(UIPreset(...)):

App	Module	Typical pages
Agents UI	ui_agents/default_app.py	chat, agents, sessions
Bot UI	ui_bot/default_app.py	chat
Chat UI	ui_chat/default_app.py	chat
Dashboard UI	ui_dashboard/default_app.py	chat, usage, sessions
Realtime UI	ui_realtime/default_app.py	chat (with realtime manager)

---

Legacy Host Mode

Set PRAISONAI_HOST_LEGACY=1 to enable callback-only handlers inside build_ui_app (@aiui.reply, @aiui.settings, @aiui.cancel).

When openai_fallback=True (legacy mode only):

• Requires OPENAI_API_KEY in the environment
• Model from PRAISONAI_MODEL or defaults to gpt-4o-mini
• Activates only after the primary agent raises an error

import os
os.environ["PRAISONAI_HOST_LEGACY"] = "1"

preset = UIPreset(
    title="Fallback Bot",
    openai_fallback=True,
    agent_kwargs={"instructions": "You are helpful."},
)
app = build_ui_app(preset)

Callable Signatures

# settings_handler — called when user changes UI settings
async def on_settings(new_settings: dict) -> None: ...

# agent_factory — returns a fresh Agent per session/settings combo
def make_agent(settings: dict | None) -> Agent: ...

---

Request Flow

---

Best Practices

Prefer agent_kwargs for static agents

When every session shares the same agent config, agent_kwargs is simpler than agent_factory.

Use agent_factory for per-user settings

When the UI settings panel changes model or instructions, agent_factory(settings) builds the right agent per session.

Keep openai_fallback off in production

Rely on your configured agent and LLM keys; enable fallback only for demos or legacy migrations.

---

Related

Host Integration

Full configure_host / build_host_app API

AIUI Backends

Backend options for PraisonAI UI