Integration Patterns

from praisonaiagents import Agent

agent = Agent(name="integration-agent", instructions="Use common integration patterns.")
agent.start("Integrate with a REST API using the webhook pattern.")

The user describes how PraisonAI should run in their stack; you pick in-process, gateway, or platform API pattern. PraisonAI supports three integration patterns for different deployment scenarios.

How It Works

Quick Start

Choose a pattern

Pattern	Best for
B — In-Process Host	Single Python app, embedded UI
C — Integrated Gateway	One port for UI + REST + WebSocket
D — Platform API	PraisonAI Cloud (planned)

Pattern B — embed in your app

from praisonai.integration import build_host_app

app = build_host_app(
    title="My Agent App",
    pages=["chat", "agents", "sessions"]
)

Pattern C — unified gateway

praisonai serve ui-gateway --style dashboard --port 8765

Pattern Decision Guide

Pattern B: In-Process Host

Embed PraisonAIUI directly in your Python application.

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.

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:

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

Deferred (P3) - Connect to PraisonAI Cloud via Platform Client

Connect PraisonAIUI to PraisonAI Cloud for managed agents.

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

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)

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

Development
Production

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

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

Migration Path

Moving between patterns as your needs evolve:

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

Best Practices

Start with Pattern B for prototypes

Embed build_host_app() in your existing FastAPI or Flask app — fastest path to a working agent UI without extra infrastructure.

Move to Pattern C for production gateways

When you need WebSocket streaming and a single deployable port, switch to run_integrated_gateway() with the same agent config.

Never hardcode tokens

Read platform tokens from environment variables in both development and production configs.

Plan a migration path

Extract shared agent config into a dict or YAML file so moving from Pattern B → C → D reuses the same definitions.

Host Integration

Implementation details

Channels Gateway

Connect agents to chat platforms

Backend Injection

Custom backend services

Gateway

Multi-channel gateway architecture

UI Presets

AIUI Backend Injection

​How It Works

​Quick Start

​Pattern Decision Guide

​Pattern B: In-Process Host

​Pattern C: Integrated Gateway

​Pattern D: Platform API

​Comparison Matrix

​Pattern Examples

​FastAPI Integration (Pattern B)

​Container Deployment (Pattern C)

​Development vs Production

​Migration Path

​Best Practices

​Related

Host Integration

Channels Gateway

Backend Injection

Gateway

How It Works

Quick Start

Pattern Decision Guide

Pattern B: In-Process Host

Pattern C: Integrated Gateway

Pattern D: Platform API

Comparison Matrix

Pattern Examples

FastAPI Integration (Pattern B)

Container Deployment (Pattern C)

Development vs Production

Migration Path

Best Practices

Related