Skip to main content

Background Tasks

Background tasks allow you to run recipes and agents asynchronously without blocking your main application. Tasks run in the background with full progress tracking, cancellation support, and result retrieval.

Python API

Running a Recipe in Background

Async callers (FastAPI / Jupyter)

arun_background is the async-native form. Use it from any running event loop — the sync run_background raises RuntimeError there instead of deadlocking. Both share the same signature (name, input, config, session_id, timeout_sec, max_concurrent, on_complete):
Never call recipe.run_background() from a running event loop — it raises RuntimeError and points you to arun_background.
Terminal-branch guarantee (PR #3883): on_complete(task) fires on every terminal branch — success, generic exception, asyncio.TimeoutError, and asyncio.CancelledError. Before #3883 it did not fire on timeout or cancel, so callers had to poll .status to detect those. Inspect task.status, task.error, and task.result inside your callback to distinguish outcomes.

BackgroundTaskHandle

The run_background() function returns a BackgroundTaskHandle with these methods:

Task Status Values

  • pending - Task is queued but not started
  • running - Task is currently executing
  • completed - Task finished successfully
  • failed - Task failed with an error
  • cancelled - Task was cancelled

Using with Agents Directly

Configuration

Safe Defaults

Background tasks use safe defaults to prevent runaway execution:

TEMPLATE.yaml Runtime Block

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

Error Handling

Best Practices

  1. Always set timeouts - Prevent tasks from running indefinitely
  2. Use session IDs - Track related tasks across executions
  3. Handle cancellation - Clean up resources when tasks are cancelled
  4. Monitor progress - Use status checks for long-running tasks
  5. Limit concurrency - Don’t overwhelm system resources

See Also