> ## 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.

# Host Integration

> Embed PraisonAIUI in your own host application for seamless agent integration

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Host Integration Flow"
        A[📋 Your App] --> B[⚙️ configure_host]
        B --> C[🔗 Bridges]
        C --> D[🎯 AIUI]
    end
    
    classDef app fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef config fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff
    
    class A app
    class B,C config
    class D output
```

## Quick Start

<Steps>
  <Step title="Simple Host">
    Create a host app with default settings:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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
    ```
  </Step>

  <Step title="Advanced Configuration">
    Configure with custom agents and settings:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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()
    ```
  </Step>
</Steps>

***

## Integration Patterns

Choose your integration pattern based on your needs:

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    A[Need Integration?] --> B{Single Process?}
    B -->|Yes| C[Pattern B<br/>In-Process Host]
    B -->|No| D{WebSocket + REST?}
    D -->|Yes| E[Pattern C<br/>Integrated Gateway]
    D -->|No| F[Pattern D<br/>Platform API]
    
    classDef pattern fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    
    class C,E,F pattern
    class A,B,D decision
```

***

## 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`        | Paths to context files (AGENTS.md-style) prepended to agent instructions |
| `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

<AccordionGroup>
  <Accordion title="configure_host()">
    Apply host settings and wire backends. Must be called before `create_host_app()`.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    configure_host(
        pages=["chat", "agents"],
        title="My App",
        agents=[{"name": "Assistant"}]
    )
    ```
  </Accordion>

  <Accordion title="create_host_app()">
    Return the Starlette app instance. Call after `configure_host()`.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    app = create_host_app()
    # Ready for uvicorn, gunicorn, etc.
    ```
  </Accordion>

  <Accordion title="build_host_app()">
    One-shot configuration and app creation. Simplest approach.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    app = build_host_app(title="Quick Setup")
    ```
  </Accordion>

  <Accordion title="run_integrated_gateway()">
    Pattern C: Start gateway with integrated UI on single port. Sync wrapper for CLI and scripts.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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"
    )
    ```
  </Accordion>
</AccordionGroup>

***

## Legacy Mode

<Warning>
  Set `PRAISONAI_HOST_LEGACY=1` to use callback-only mode without provider wiring. This skips automatic backend integration.
</Warning>

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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)
```

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

***

## Best Practices

<AccordionGroup>
  <Accordion title="Environment Configuration">
    Use environment variables for configuration that changes between deployments:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    configure_host(
        title=os.getenv("APP_TITLE", "PraisonAI"),
        agents=[{
            "llm": os.getenv("PRAISONAI_MODEL", "gpt-4o-mini")
        }]
    )
    ```
  </Accordion>

  <Accordion title="Error Handling">
    Handle import errors gracefully for optional features:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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()
    ```
  </Accordion>

  <Accordion title="Resource Cleanup">
    Use context managers for proper cleanup in long-running applications:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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
    ```
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Integration Patterns" icon="diagram-project" href="/docs/features/integration-patterns">
    Compare Pattern B vs C vs D
  </Card>

  <Card title="Backend Injection" icon="arrows-right-left" href="/docs/features/aiui-backends">
    Custom backend services
  </Card>
</CardGroup>