Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

Integrate PraisonAI agents directly into your application using the built-in host integration module.

​
Quick Start

1

Simple Host

Create a host app with default settings:
from praisonai.integration import build_host_app

app = build_host_app(
    title="My Agent App",
    pages=["chat", "agents", "sessions", "usage"],
)
# Run with: uvicorn main:app --host 0.0.0.0 --port 8000
2

Advanced Configuration

Configure with custom agents and settings:
from praisonai.integration import configure_host, create_host_app

configure_host(
    title="Advanced Agent Platform",
    logo="🚀",
    pages=["chat", "agents", "memory", "knowledge", "sessions"],
    agents=[
        {
            "name": "Code Assistant",
            "instructions": "Help with coding tasks",
            "llm": "gpt-4o"
        }
    ],
    theme={"primary_color": "#3b82f6"}
)

app = create_host_app()

​
Integration Patterns

Choose your integration pattern based on your needs:

​
Configuration Options

OptionTypeDefaultDescription
pagesSequence[str]NoneUI pages to include
titlestr"PraisonAI"Application title
logostr"🤖"Logo or emoji
sidebarboolTrueShow navigation sidebar
page_headerboolTrueShow page header
themeDict[str, Any]NoneCustom theme settings
agentsList[Any]NonePre-configured agents
agent_kwargsDict[str, Any]NoneDefault agent parameters
gatewayAnyNoneExternal gateway reference
modulesSequence[str]NoneAdditional modules to load

​
API Reference

​
Core Functions

Apply host settings and wire backends. Must be called before create_host_app().
configure_host(
    pages=["chat", "agents"],
    title="My App",
    agents=[{"name": "Assistant"}]
)
Return the Starlette app instance. Call after configure_host().
app = create_host_app()
# Ready for uvicorn, gunicorn, etc.
One-shot configuration and app creation. Simplest approach.
app = build_host_app(title="Quick Setup")
Pattern C: Start gateway with integrated UI on single port (async).
await run_integrated_gateway(
    port=8080,
    title="Gateway App",
    pages=["chat", "agents"]
)

​
Legacy Mode

Set PRAISONAI_HOST_LEGACY=1 to use callback-only mode without provider wiring. This skips automatic backend integration.
export PRAISONAI_HOST_LEGACY=1
In legacy mode, only @aiui.reply callbacks work - no automatic agent integration.

​
Common Patterns

​
Pattern B: In-Process Host

Embed the UI in your existing application: 
from praisonai.integration import build_host_app
from fastapi import FastAPI

# Your existing app
main_app = FastAPI()

# Create agent UI
agent_ui = build_host_app(
    title="Agent Dashboard",
    pages=["chat", "sessions"]
)

# Mount as subapp
main_app.mount("/agents", agent_ui)

​
Pattern C: Integrated Gateway

Single process serving UI + API + WebSocket: 
import asyncio
from praisonai.integration import run_integrated_gateway

async def main():
    await run_integrated_gateway(
        port=8080,
        host="0.0.0.0",
        title="Agent Gateway",
        agents=[{"name": "Assistant", "llm": "gpt-4o"}]
    )

if __name__ == "__main__":
    asyncio.run(main())

​
Custom Bridges

Wire your own backend services: 
from praisonai.integration import configure_host, setup_bridges

configure_host(title="Custom App")
setup_bridges()  # Auto-wire available bridges

# Or set custom backends
import praisonaiui.backends as backends
backends.set_backend("usage_sink", my_custom_sink)

​
Best Practices

Use environment variables for configuration that changes between deployments:
configure_host(
    title=os.getenv("APP_TITLE", "PraisonAI"),
    agents=[{
        "llm": os.getenv("PRAISONAI_MODEL", "gpt-4o-mini")
    }]
)
Handle import errors gracefully for optional features:
try:
    from praisonai.integration import build_host_app
    app = build_host_app()
except ImportError:
    # Fallback for environments without UI
    from fastapi import FastAPI
    app = FastAPI()
Use context managers for proper cleanup in long-running applications:
from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app):
    # Startup
    setup_bridges()
    yield
    # Cleanup - bridges handle themselves

app = build_host_app()
app.router.lifespan_context = lifespan

Integration Patterns

Compare Pattern B vs C vs D

Backend Injection

Custom backend services