Integration Patterns

Choose the right pattern for integrating PraisonAI into your application

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

1. 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)

2. 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"]
   )

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

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

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

# 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

Related