Background Tasks Deployment

Deploy and manage background task execution for agents and recipes

Background Tasks Deployment

Deploy background task execution for running agents and recipes asynchronously in production environments.

Overview

Background tasks allow you to:

• Run recipes and agents without blocking
• Track progress and status
• Cancel running tasks
• Manage concurrent execution

Quick Start

Python Deployment

from praisonai import recipe

# Submit recipe as background task
task = recipe.run_background(
    "my-recipe",
    input={"query": "What is AI?"},
    config={"max_tokens": 1000},
    session_id="session_123",
    timeout_sec=300,
)

print(f"Task ID: {task.task_id}")

# Check status
status = await task.status()

# Wait for completion
result = await task.wait(timeout=600)

Async callers (FastAPI / Jupyter)

From within a running event loop, use arun_background. The sync run_background raises RuntimeError in that context instead of deadlocking:

from praisonai import recipe

async def handler():
    task = await recipe.arun_background(
        "my-recipe",
        input={"query": "What is AI?"},
        config={"max_tokens": 1000},
    )
    return await task.wait()

Never call recipe.run_background() from a running event loop — it raises RuntimeError and points you to arun_background.

CLI Deployment

# Submit a recipe as background task
praisonai background submit --recipe my-recipe

# With input data
praisonai background submit --recipe my-recipe --input '{"query": "test"}'

# List tasks
praisonai background list

# Check status
praisonai background status <task_id>

Configuration

Safe Defaults

Setting	Default	Description
timeout_sec	300	Maximum execution time (5 minutes)
max_concurrent	5	Maximum concurrent tasks
cleanup_delay_sec	3600	Time before completed tasks are cleaned up

TEMPLATE.yaml Runtime Block

Configure background task defaults in your recipe’s TEMPLATE.yaml:

runtime:
  background:
    enabled: true
    max_concurrent: 3
    cleanup_delay_sec: 3600

Docker Deployment

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Copy application
COPY . .

# Set environment variables
ENV OPENAI_API_KEY=${OPENAI_API_KEY}

# Run background task processor
CMD ["python", "-m", "praisonai.background.worker"]

Production Considerations

Concurrency Limits

Set appropriate concurrency limits based on your infrastructure:

from praisonaiagents.background import BackgroundRunner, BackgroundConfig

config = BackgroundConfig(
    max_concurrent_tasks=10,  # Adjust based on resources
    default_timeout=600.0,
    auto_cleanup=True
)

runner = BackgroundRunner(config=config)

Monitoring

Monitor background tasks using the CLI:

# List all tasks with status
praisonai background list --json | jq '.tasks[] | {id, status, duration}'

# Filter by status
praisonai background list --status running

Error Handling

from praisonai import recipe
from praisonai.recipe import RecipeError

try:
    task = recipe.run_background("my-recipe", input="test")
    result = await task.wait(timeout=60)
except RecipeError as e:
    print(f"Recipe error: {e}")
except TimeoutError:
    print("Task timed out")
    await task.cancel()

See Also

• Background Tasks Feature
• Background Tasks CLI
• Async Jobs Deployment
• Scheduler Deployment