Integration Models

6 ways to integrate PraisonAI recipes into your applications

Compare six ways to run PraisonAI recipes—from in-process Python to remote managed runners.

from praisonaiagents import Agent

agent = Agent(
    name="Recipe Integrator",
    instructions="Explain trade-offs between recipe integration models.",
)
agent.start("We need the lowest latency inside a Django app.")

The user chooses a model from the overview table, then follows the linked deep-dive page.

PraisonAI recipes can be integrated into your applications using six distinct models. Each model has specific use cases, trade-offs, and implementation patterns.

Model Overview

Model	Latency	Complexity	Best For
1. Embedded SDK	Lowest	Low	Python apps, notebooks
2. CLI Invocation	Low	Low	Scripts, CI/CD
3. Local HTTP Sidecar	Medium	Medium	Microservices, polyglot
4. Remote Managed Runner	Medium	High	Multi-tenant, cloud
5. Event-Driven	Variable	High	Async workflows
6. Plugin Mode	Low	Medium	IDE/CMS extensions

---

Model 1 — Embedded Python SDK (In-Process)

When to Use

• Python application (backend, notebook, script)
• Need lowest latency (no network hop)
• Single-tenant or trusted environment
• Direct access to recipe outputs

How It Works

Pros

• Zero network latency
• Direct memory access to results
• Simplest integration
• Full Python ecosystem available

Cons

• Python-only
• Recipe runs in same process (resource sharing)
• No built-in multi-tenancy

Step-by-Step Tutorial

1. Install PraisonAI

   pip install praisonai
   
2. Set API Keys

   export OPENAI_API_KEY=your-key
   
3. Run a Recipe

   from praisonai import recipe
   
   # List available recipes
   recipes = recipe.list_recipes()
   print(f"Found {len(recipes)} recipes")
   
   # Run a recipe
   result = recipe.run(
       "my-recipe",
       input={"query": "Summarize this document"},
       options={"timeout_sec": 60}
   )
   
   if result.ok:
       print(f"Success: {result.output}")
   else:
       print(f"Error: {result.error}")
   
4. Stream Results

   for event in recipe.run_stream("my-recipe", input={"query": "Hello"}):
       print(f"[{event.event_type}] {event.data}")
   

Troubleshooting

• ImportError: Ensure pip install praisonai completed
• Recipe not found: Run praisonai recipe list to see available recipes
• API key error: Verify OPENAI_API_KEY is set

---

Model 2 — CLI Invocation (Subprocess)

When to Use

• Shell scripts, CI/CD pipelines
• Language-agnostic invocation
• Quick prototyping
• Batch processing

How It Works

Pros

• Works from any language
• Simple JSON output parsing
• No SDK dependency in calling app
• Easy to debug

Cons

• Process spawn overhead
• Stdout/stderr parsing required
• No streaming (unless using —stream)

Step-by-Step Tutorial

1. Verify CLI Installation

   praisonai --help
   
2. List Recipes

   praisonai recipe list --json
   
3. Run Recipe with JSON Output

   praisonai recipe run my-recipe \
     --input '{"query": "Hello"}' \
     --json
   
4. Parse Output in Your App

   import subprocess
   import json
   
   result = subprocess.run(
       ["praisonai", "recipe", "run", "my-recipe",
        "--input", '{"query": "Hello"}', "--json"],
       capture_output=True,
       text=True
   )
   
   data = json.loads(result.stdout)
   print(f"Run ID: {data['run_id']}")
   print(f"Output: {data['output']}")
   

Troubleshooting

• Command not found: Add praisonai to PATH or use full path
• JSON parse error: Ensure --json flag is used
• Exit code non-zero: Check stderr for error details

---

Model 3 — Local HTTP “Recipe Runner” Sidecar

When to Use

• Microservices architecture
• Non-Python services need recipe access
• Want HTTP API without cloud deployment
• Development/staging environments

How It Works

Pros

• Language-agnostic (HTTP)
• Supports streaming (SSE)
• Process isolation
• Easy to scale horizontally

Cons

• Network latency (localhost)
• Need to manage server lifecycle
• Port management

Step-by-Step Tutorial

1. Install Serve Dependencies

   pip install praisonai[serve]
   
2. Start the Server

   praisonai serve recipe --port 8765
   
3. Check Health

   curl http://localhost:8765/health
   
4. List Recipes via HTTP

   curl http://localhost:8765/v1/recipes
   
5. Run Recipe via HTTP

   curl -X POST http://localhost:8765/v1/recipes/run \
     -H "Content-Type: application/json" \
     -d '{"recipe": "my-recipe", "input": {"query": "Hello"}}'
   
6. Use Endpoints CLI

   # Health check
   praisonai endpoints health
   
   # List endpoints
   praisonai endpoints list --format json
   
   # Invoke endpoint
   praisonai endpoints invoke my-recipe \
     --input-json '{"query": "Hello"}' \
     --json
   

Troubleshooting

• Connection refused: Ensure server is running
• Port in use: Use --port to specify different port
• Missing deps: Run pip install praisonai[serve]

---

Model 4 — Remote Managed Runner (Self-Hosted or Cloud)

When to Use

• Production multi-tenant deployments
• Need authentication/authorization
• Centralized recipe management
• Cloud-native architecture

How It Works

Pros

• Centralized management
• Built-in auth/audit
• Scalable infrastructure
• Multi-tenant support

Cons

• Network latency
• Infrastructure complexity
• Requires auth setup

Step-by-Step Tutorial

1. Start Server with Auth

   # Set API key
   export PRAISONAI_API_KEY=your-secret-key
   
   # Start with auth enabled
   praisonai serve recipe \
     --host 0.0.0.0 \
     --port 8765 \
     --auth api-key
   
2. Configure Client

   export PRAISONAI_ENDPOINTS_URL=https://api.example.com
   export PRAISONAI_ENDPOINTS_API_KEY=your-secret-key
   
3. Invoke with Auth

   praisonai endpoints invoke my-recipe \
     --input-json '{"query": "Hello"}' \
     --api-key your-secret-key \
     --url https://api.example.com
   
4. HTTP with Auth Header

   curl -X POST https://api.example.com/v1/recipes/run \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your-secret-key" \
     -d '{"recipe": "my-recipe", "input": {"query": "Hello"}}'
   

Troubleshooting

• 401 Unauthorized: Check API key header
• Connection timeout: Verify network/firewall
• TLS errors: Ensure valid certificates

---

Model 5 — Event-Driven Invocation (Queue/Stream)

When to Use

• Asynchronous processing
• High-volume batch jobs
• Decoupled architectures
• Long-running workflows

How It Works

Pros

• Fully async
• Handles backpressure
• Retry/dead-letter support
• Scales independently

Cons

• Infrastructure complexity
• Eventual consistency
• Debugging harder

Step-by-Step Tutorial

1. Define Worker Script

   # worker.py
   import redis
   import json
   from praisonai import recipe
   
   r = redis.Redis()
   pubsub = r.pubsub()
   pubsub.subscribe('recipe-jobs')
   
   for message in pubsub.listen():
       if message['type'] == 'message':
           job = json.loads(message['data'])
           result = recipe.run(
               job['recipe'],
               input=job['input']
           )
           r.publish('recipe-results', json.dumps({
               'job_id': job['job_id'],
               'result': result.to_dict()
           }))
   
2. Publish Job

   import redis
   import json
   import uuid
   
   r = redis.Redis()
   job_id = str(uuid.uuid4())
   
   r.publish('recipe-jobs', json.dumps({
       'job_id': job_id,
       'recipe': 'my-recipe',
       'input': {'query': 'Process this'}
   }))
   
3. Consume Results

   pubsub = r.pubsub()
   pubsub.subscribe('recipe-results')
   
   for message in pubsub.listen():
       if message['type'] == 'message':
           result = json.loads(message['data'])
           print(f"Job {result['job_id']}: {result['result']}")
   

---

Model 6 — Plugin Mode (CMS/IDE/Chat Extensions)

When to Use

• IDE extensions (VS Code, JetBrains)
• CMS plugins (WordPress, Strapi)
• Chat integrations (Slack, Discord)
• Browser extensions

How It Works

Pros

• Native UX integration
• Leverages host app features
• User-friendly
• Context-aware

Cons

• Platform-specific
• Sandboxing limitations
• Update management

Step-by-Step Tutorial

1. Create Plugin Manifest

   {
     "name": "praisonai-plugin",
     "version": "1.0.0",
     "recipes": ["code-review", "doc-generator"],
     "endpoints": {
       "base_url": "http://localhost:8765"
     }
   }
   
2. Implement Plugin Handler

   // plugin.js
   async function invokeRecipe(recipeName, input) {
     const response = await fetch(
       `${config.endpoints.base_url}/v1/recipes/run`,
       {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ recipe: recipeName, input })
       }
     );
     return response.json();
   }
   
   // Register command
   registerCommand('praisonai.runRecipe', async () => {
     const result = await invokeRecipe('code-review', {
       code: getSelectedText()
     });
     showOutput(result.output);
   });
   

---

Decision Guide

Use this flowchart to choose the right model:

Next Steps

• Explore Use Cases for real-world patterns
• Review Personas for role-specific guidance
• Check the CLI Reference for command details