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

# Integration Patterns

> Choose the right pattern for integrating PraisonAI into your application

PraisonAI supports three integration patterns for different deployment scenarios.

## Pattern Decision Guide

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TD
    A[Need PraisonAI Integration?] --> B{Single Python Process?}
    B -->|Yes| C[Pattern B<br/>In-Process Host]
    B -->|No| D{WebSocket + REST + UI<br/>on Same Port?}
    D -->|Yes| E[Pattern C<br/>Integrated Gateway]
    D -->|No| F{Using PraisonAI Cloud?}
    F -->|Yes| G[Pattern D<br/>Platform API]
    F -->|No| H[Custom Architecture]
    
    classDef pattern fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef cloud fill:#6366F1,stroke:#7C90A0,color:#fff
    
    class C,E,G pattern
    class A,B,D,F decision
    class H cloud
```

***

## Pattern B: In-Process Host

Embed PraisonAIUI directly in your Python application.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Single Process"
        A[Your App] --> B[configure_host]
        B --> C[PraisonAIUI]
        C --> D[Agents]
    end
    
    classDef app fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef config fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef ui fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#10B981,stroke:#7C90A0,color:#fff
    
    class A app
    class B config
    class C ui
    class D agent
```

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

# Run with uvicorn main:app
```

**When to Use:**

* Single application deployment
* Direct Python integration needed
* Simple agent interactions
* Development and testing

**When NOT to Use:**

* Need separate UI and API processes
* Complex microservice architecture
* High-scale production deployments

***

## Pattern C: Integrated Gateway

Single process serving UI, REST API, and WebSocket on one port.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Gateway Process"
        A[Client] --> B[Port 8765]
        B --> C[UI Routes]
        B --> D[REST API]
        B --> E[WebSocket]
        C --> F[Agents]
        D --> F
        E --> F
    end
    
    classDef client fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef port fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef service fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#10B981,stroke:#7C90A0,color:#fff
    
    class A client
    class B port
    class C,D,E service
    class F agent
```

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

Or via CLI:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai serve ui-gateway --style dashboard --port 8765
```

**When to Use:**

* Need unified endpoint for UI + API
* WebSocket real-time communication required
* Single-port deployment constraints
* Container deployment scenarios

**When NOT to Use:**

* Want separate scaling of UI vs API
* Complex routing requirements
* Need multiple protocol support

***

## Pattern D: Platform API

<Info>Deferred (P3) - Connect to PraisonAI Cloud via Platform Client</Info>

Connect PraisonAIUI to PraisonAI Cloud for managed agents.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Your Infrastructure"
        A[PraisonAIUI] --> B[Platform Client]
    end
    subgraph "PraisonAI Cloud"
        C[Platform API] --> D[Managed Agents]
    end
    B --> C
    
    classDef local fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef cloud fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef agent fill:#10B981,stroke:#7C90A0,color:#fff
    
    class A,B local
    class C cloud
    class D agent
```

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Future implementation
from praisonai.integration import configure_host

configure_host(
    title="Cloud Agents",
    platform_token=os.getenv("PRAISONAI_PLATFORM_TOKEN")
)
```

**When Available:**

* Cloud-managed agent infrastructure
* Multi-tenant deployments
* Enterprise security requirements
* Global agent orchestration

***

## Comparison Matrix

| Feature         | Pattern B         | Pattern C      | Pattern D        |
| --------------- | ----------------- | -------------- | ---------------- |
| **Complexity**  | Low               | Medium         | High             |
| **Setup Time**  | Minutes           | Minutes        | TBD              |
| **Scalability** | Application-bound | Single-process | Cloud-scale      |
| **Real-time**   | Via callbacks     | WebSocket      | Platform streams |
| **Deployment**  | Embedded          | Standalone     | Distributed      |
| **Use Cases**   | Apps, Prototypes  | Gateways, APIs | Enterprise, SaaS |

***

## Pattern Examples

### FastAPI Integration (Pattern B)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from fastapi import FastAPI
from praisonai.integration import build_host_app

main_app = FastAPI()

# Your API routes
@main_app.get("/api/health")
def health():
    return {"status": "healthy"}

# Mount agent UI
agent_ui = build_host_app(
    title="Agent Dashboard",
    pages=["chat", "agents"]
)
main_app.mount("/agents", agent_ui)

# Access at: http://localhost:8000/agents
```

### Container Deployment (Pattern C)

```dockerfile theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
FROM python:3.11
COPY . /app
WORKDIR /app
RUN pip install praisonai[ui]
EXPOSE 8765
CMD ["praisonai", "serve", "ui-gateway", "--host", "0.0.0.0", "--port", "8765"]
```

### Development vs Production

<Tabs>
  <Tab title="Development">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Quick development setup
    from praisonai.integration import build_host_app

    app = build_host_app(
        title="Dev Agent",
        pages=["chat", "agents", "logs"],
        agent_kwargs={"llm": "gpt-4o-mini"}
    )
    ```
  </Tab>

  <Tab title="Production">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Production-ready gateway
    import os
    from praisonai import run_integrated_gateway

    run_integrated_gateway(
        port=int(os.getenv("PORT", "8765")),
        host="0.0.0.0",
        title=os.getenv("APP_TITLE", "Agent Gateway"),
        style=os.getenv("UI_STYLE", "dashboard"),
        agents=[{
            "name": "Production Assistant",
            "llm": os.getenv("PRAISONAI_MODEL", "gpt-4o"),
            "instructions": "You are a production assistant."
        }],
        ui_config={
            "analytics": os.getenv("ANALYTICS_ID"),
            "theme": "production"
        }
    )
    ```
  </Tab>
</Tabs>

***

## Migration Path

Moving between patterns as your needs evolve:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start with Pattern B (embedded)
app = build_host_app(title="MVP")

# Migrate to Pattern C (gateway)
# Extract configuration:
config = {
    "title": "MVP",
    "agents": [...],
    "pages": [...]
}

# Use in gateway:
run_integrated_gateway(**config)

# Future: Pattern D (cloud)
# Same config, different backend
configure_host(platform_token="...", **config)
```

***

## Related

<CardGroup cols={2}>
  <Card title="Host Integration" icon="plug" href="/docs/features/host-integration">
    Implementation details
  </Card>

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