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

​
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

FieldTypeDefaultDescription
titlestr"PraisonAI"Browser tab and header title
logostr"🤖"Logo emoji or text in the sidebar
pagesList[str]["chat"]Enabled UI pages (chat, agents, sessions, …)
themeDictblue preset, dark modeTheme dict passed to configure_host
agent_kwargsDict{}Keyword args for default Agent(...)
startersList[Dict][]Conversation starter chips
welcomestrgreeting messageShown on first load via @aiui.welcome
sidebarboolTrueShow sidebar navigation
page_headerboolTrueShow page header bar
openai_fallbackboolFalseFall back to OpenAI when agent errors (legacy mode)
settings_handlerCallable | NoneNoneAsync (new_settings) -> None on settings change
agent_factoryCallable | NoneNone(settings) -> Agent for per-session agents
realtime_managerAny | NoneNoneOpenAI realtime manager instance
agent_loaderCallable | NoneNoneLoad agents from YAML at startup

​
Default App Patterns

All five bundled UI apps now use build_ui_app(UIPreset(...)):
AppModuleTypical pages
Agents UIui_agents/default_app.pychat, agents, sessions
Bot UIui_bot/default_app.pychat
Chat UIui_chat/default_app.pychat
Dashboard UIui_dashboard/default_app.pychat, usage, sessions
Realtime UIui_realtime/default_app.pychat (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

When every session shares the same agent config, agent_kwargs is simpler than agent_factory.
When the UI settings panel changes model or instructions, agent_factory(settings) builds the right agent per session.
Rely on your configured agent and LLM keys; enable fallback only for demos or legacy migrations.

Host Integration

Full configure_host / build_host_app API

AIUI Backends

Backend options for PraisonAI UI