> ## Documentation Index > Fetch the complete documentation index at: https://docs.praison.ai/llms.txt > Use this file to discover all available pages before exploring further. # Background Tasks > Run agent tasks and recipes asynchronously in the background The `background` command manages background task execution for agents and recipes. ## Quick Start ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ` | Get task status | | `praisonai background cancel ` | 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: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Get status praisonai background status # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Cancel task praisonai background cancel # JSON output praisonai background cancel task_abc123 --json ``` ## Clear Completed Tasks ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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() ``` ### Using BackgroundRunner Directly ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} #!/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" ``` ## See Also * [Background Tasks Feature](/docs/features/background-tasks) * [Async Jobs CLI](/docs/cli/async-jobs) * [Scheduler CLI](/docs/cli/scheduler) * [Background Tasks SDK](/docs/sdk/praisonai/background-tasks)