Background Tasks

The background command manages background task execution for agents and recipes.

Quick Start

# List running background tasks
praisonai background list

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

Commands Overview

Command	Description
`praisonai background list`	List all background tasks
`praisonai background status <id>`	Get task status
`praisonai background cancel <id>`	Cancel a running task
`praisonai background clear`	Clear completed tasks
`praisonai background submit`	Submit a recipe as background task

Submit a Recipe

Submit a recipe to run in the background:

# Basic submission
praisonai background submit --recipe my-recipe

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

# With config overrides
praisonai background submit --recipe my-recipe --config '{"max_tokens": 1000}'

# With session ID
praisonai background submit --recipe my-recipe --session-id session_123

# With timeout
praisonai background submit --recipe my-recipe --timeout 600

# JSON output for scripting
praisonai background submit --recipe my-recipe --json

Submit Options

Option	Short	Description
`--recipe`		Recipe name to execute (required)
`--input`	`-i`	Input data as JSON string
`--config`	`-c`	Config overrides as JSON string
`--session-id`	`-s`	Session ID for conversation continuity
`--timeout`		Timeout in seconds (default: 300)
`--json`		Output JSON for scripting

Alternative: Recipe Run with Background Flag

You can also use the recipe run command with the --background flag:

# Run recipe in background
praisonai recipe run my-recipe --background

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

# With session ID
praisonai recipe run my-recipe --background --session-id session_123

List Tasks

# List all tasks
praisonai background list

# Filter by status
praisonai background list --status running
praisonai background list --status completed
praisonai background list --status failed

# Pagination
praisonai background list --page 1 --page-size 20

# JSON output
praisonai background list --json

Expected Output:

╭─ Background Tasks ──────────────────────────────────────────────────────────╮
│  🔄 [abc12345] research_task - running (45s)                                │
│  ✅ [def67890] analysis_task - completed                                    │
│  ❌ [ghi11111] failed_task - failed                                         │
╰──────────────────────────────────────────────────────────────────────────────╯

Check Task Status

# Get status
praisonai background status <task_id>

# JSON output
praisonai background status task_abc123 --json

Status Output

Task: task_abc123
Status: running
Progress: 45%
Duration: 12.5s
Recipe: my-recipe
Session: session_123

Cancel Task

# Cancel task
praisonai background cancel <task_id>

# JSON output
praisonai background cancel task_abc123 --json

Clear Completed Tasks

# Clear completed tasks
praisonai background clear

# Clear all tasks (including running)
praisonai background clear --all

# Clear tasks older than N seconds
praisonai background clear --older-than 3600

# JSON output
praisonai background clear --json

Python API

Using Recipe Operations

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}")
print(f"Session: {task.session_id}")

# Check status
status = await task.status()
print(f"Status: {status}")

# Wait for completion
result = await task.wait(timeout=600)
print(f"Result: {result}")

# Cancel if needed
await task.cancel()

Async callers (FastAPI / Jupyter)

Inside a running event loop, use arun_background. The sync run_background raises RuntimeError there 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.

Using BackgroundRunner Directly

import asyncio
from praisonaiagents.background import BackgroundRunner, BackgroundConfig

async def main():
    config = BackgroundConfig(max_concurrent_tasks=3)
    runner = BackgroundRunner(config=config)
    
    async def my_task(name: str) -> str:
        await asyncio.sleep(2)
        return f"Task {name} done"
    
    task = await runner.submit(my_task, args=("example",))
    await task.wait(timeout=10.0)
    print(task.result)

asyncio.run(main())

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

Complete Workflow Example

# 1. Submit a recipe
praisonai background submit --recipe news-monitor --input '{"topic": "AI"}' --json
# Output: {"ok": true, "task_id": "task_abc123", "recipe": "news-monitor", "session_id": "session_xyz"}

# 2. Check status
praisonai background status task_abc123

# 3. Wait and check again
sleep 30
praisonai background status task_abc123

# 4. List all tasks
praisonai background list

# 5. Clear completed
praisonai background clear

Scripting with JSON Output

#!/bin/bash

# Submit and capture task ID
RESULT=$(praisonai background submit --recipe my-recipe --json)
TASK_ID=$(echo $RESULT | jq -r '.task_id')

echo "Submitted task: $TASK_ID"

# Poll for completion
while true; do
    STATUS=$(praisonai background status $TASK_ID --json | jq -r '.status')
    echo "Status: $STATUS"
    
    if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
        break
    fi
    
    sleep 5
done

echo "Task finished with status: $STATUS"

Inspect the same tasks from chat

praisonai background list and the in-conversation /tasks command read the same process-wide runner (get_background_runner()), so tasks submitted here are also visible from the REPL, TUI, and bot chats.

/tasks                 # list background tasks (id, name, status, progress)
/tasks <id>            # detail view (incl. result / error)
/tasks cancel <id>     # cancel a running task

In bot chats /tasks is per-user scoped — a caller only sees and cancels tasks whose metadata["user_id"] matches. See Bot Chat Commands → /tasks.

CLI

Quick Start

Commands Overview

Submit a Recipe

Submit Options

Alternative: Recipe Run with Background Flag

List Tasks

Check Task Status

Status Output

Cancel Task

Clear Completed Tasks

Python API

Using Recipe Operations

Async callers (FastAPI / Jupyter)

Using BackgroundRunner Directly

Safe Defaults

Complete Workflow Example

Scripting with JSON Output

Inspect the same tasks from chat

See Also

​Quick Start

​Commands Overview

​Submit a Recipe

​Submit Options

​Alternative: Recipe Run with Background Flag

​List Tasks

​Check Task Status

​Status Output

​Cancel Task

​Clear Completed Tasks

​Python API

​Using Recipe Operations

​Async callers (FastAPI / Jupyter)

​Using BackgroundRunner Directly

​Safe Defaults

​Complete Workflow Example

​Scripting with JSON Output

​Inspect the same tasks from chat

​See Also

Quick Start

Commands Overview

Submit a Recipe

Submit Options

Alternative: Recipe Run with Background Flag

List Tasks

Check Task Status

Status Output

Cancel Task

Clear Completed Tasks

Python API

Using Recipe Operations

Async callers (FastAPI / Jupyter)

Using BackgroundRunner Directly

Safe Defaults

Complete Workflow Example

Scripting with JSON Output

Inspect the same tasks from chat

See Also