Host Integration - PraisonAI

from praisonaiagents import Agent

agent = Agent(name="host-agent", instructions="Integrate with the host environment.")
agent.start("Connect to the host system and retrieve environment variables.")

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

Just want a UI quickly? Use UIPreset + build_ui_app() — see UI Presets.

The user interacts through the host app; PraisonAIUI bridges agent output into the host UI.

How It Works

Quick Start

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

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()

When to Use `build_host_app` vs `build_ui_app`

Both APIs remain supported. Choose based on how much control you need:

Pattern	Best for
`build_ui_app(UIPreset(...))`	Chat/dashboard/bot UIs with sensible defaults
`build_host_app(...)`	Quick host with keyword arguments
`configure_host` + `create_host_app`	Custom bridges, agents list, theme hooks

Integration Patterns

Choose your integration pattern based on your needs:

Configuration Options

Option	Type	Default	Description
`pages`	`Sequence[str]`	`None`	UI pages to include
`title`	`str`	`"PraisonAI"`	Application title
`logo`	`str`	`"🤖"`	Logo or emoji
`sidebar`	`bool`	`True`	Show navigation sidebar
`page_header`	`bool`	`True`	Show page header
`style`	`str`	`"dashboard"`	UI layout: `"dashboard"` or `"chat"`
`context_paths`	`Sequence[str]`	`None`	Context file paths. `None` → walk-up auto-discovery from `context_cwd` (or process cwd). `[]` → authoritative “load nothing” sentinel; discovery is skipped. `["AGENTS.md", ...]` → load exactly those paths from cwd; no walk-up.
`no_context`	`bool`	`False`	Skip all project-context loading. Honoured as a first-class param and when threaded through `agent_kwargs={"no_context": True}` (backward compat).
`context_cwd`	`Optional[str]`	`None`	Starting directory for walk-up discovery. Falls back to process cwd. Ignored when `context_paths` is explicitly provided.
`context_token_budget`	`int`	`8000`	Maximum characters of discovered context to inject. Excess is truncated and `\n... [project context truncated]` is appended.
`theme`	`Dict[str, Any]`	`None`	Custom theme settings
`agents`	`List[Any]`	`None`	Pre-configured agents
`agent_kwargs`	`Dict[str, Any]`	`None`	Default agent parameters
`gateway`	`Any`	`None`	External gateway reference
`modules`	`Sequence[str]`	`None`	Additional modules to load

API Reference

Core Functions

configure_host()

Apply host settings and wire backends. Must be called before create_host_app().

configure_host(
    pages=["chat", "agents"],
    title="My App",
    agents=[{"name": "Assistant"}]
)

create_host_app()

Return the Starlette app instance. Call after configure_host().

app = create_host_app()
# Ready for uvicorn, gunicorn, etc.

build_host_app()

One-shot configuration and app creation. Simplest approach.

app = build_host_app(title="Quick Setup")

run_integrated_gateway()

Pattern C: Start gateway with integrated UI on single port. Sync wrapper for CLI and scripts.

from praisonai import run_integrated_gateway

run_integrated_gateway(
    port=8765,
    title="Gateway App",
    style="dashboard",
    context_paths=["AGENTS.md"]
)

For async usage, use the async variant:

from praisonai.integration.gateway_host import run_integrated_gateway_async

await run_integrated_gateway_async(
    port=8765,
    host="127.0.0.1",
    title="Gateway App"
)

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 via CLI

Use the integrated UI-Gateway command for quick setup:

# Basic UI-Gateway
praisonai serve ui-gateway

# With custom settings
praisonai serve ui-gateway --style chat --title "My App" --port 8765

# With agents file
praisonai serve ui-gateway --agents agents.yaml --style dashboard

Pattern C: Integrated Gateway

Single process serving UI + API + WebSocket:

from praisonai import run_integrated_gateway

run_integrated_gateway(
    port=8765,
    host="0.0.0.0", 
    title="Agent Gateway",
    style="dashboard",
    agents=[{"name": "Assistant", "llm": "gpt-4o"}]
)

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)

Bridge failures are now logged as warnings for non-ImportError exceptions (previously debug level). This improves visibility when optional services fail to initialize.

Best Practices

Environment Configuration

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")
    }]
)

Error Handling

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()

Resource Cleanup

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

Out-of-Process Relay Transport

UI Presets

​How It Works

​Quick Start

​When to Use build_host_app vs build_ui_app

​Integration Patterns

​Configuration Options

​API Reference

​Core Functions

​Legacy Mode

​Common Patterns

​Pattern B: In-Process Host

​Pattern C via CLI

​Pattern C: Integrated Gateway

​Custom Bridges

​Best Practices

​Related

Integration Patterns

Backend Injection

How It Works

Quick Start

When to Use `build_host_app` vs `build_ui_app`

Integration Patterns

Configuration Options

API Reference

Core Functions

Legacy Mode

Common Patterns

Pattern B: In-Process Host

Pattern C via CLI

Pattern C: Integrated Gateway

Custom Bridges

Best Practices

Related