> ## 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 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

```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}")

# Check status
status = await task.status()

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

### CLI Deployment

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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`:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
runtime:
  background:
    enabled: true
    max_concurrent: 3
    cleanup_delay_sec: 3600
```

## Docker Deployment

```dockerfile theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List all tasks with status
praisonai background list --json | jq '.tasks[] | {id, status, duration}'

# Filter by status
praisonai background list --status running
```

### Error Handling

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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](/docs/features/background-tasks)
* [Background Tasks CLI](/docs/cli/background)
* [Async Jobs Deployment](/docs/deploy/async-jobs)
* [Scheduler Deployment](/docs/deploy/scheduler)