# Background Jobs Boundaries

> Guardrails for background work in FastAPI and Python services. Prevent misuse of in-process background execution (e.g. FastAPI BackgroundTasks).

- **Type:** Skill
- **Install:** `agentstack add skill-robhowley-py-pit-skills-background-jobs-boundaries`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [robhowley](https://agentstack.voostack.com/s/robhowley)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [robhowley](https://github.com/robhowley)
- **Source:** https://github.com/robhowley/py-pit-skills/tree/main/skills/background-jobs-boundaries

## Install

```sh
agentstack add skill-robhowley-py-pit-skills-background-jobs-boundaries
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill: background-jobs-boundaries

## Core stance

In-process background tasks are **best-effort follow-ups**, not job infrastructure.

Use them only for **small, fast, non-critical work** after a request completes.

---

## Do not use background tasks when the work is:

- long-running
- business-critical
- requires retries
- requires durability
- must run exactly once

These require a **real job system**.

---

## Hard rules

- Never pass `Request`, DB sessions, ORM objects, or DI state.
- Persist domain state **before** triggering background work.
- Do not implement retry logic inside tasks.
- Do not spawn threads or `asyncio.create_task()` inside handlers.
- Pass **IDs or payloads**, reload resources inside the task.

---

## Acceptable uses

Small follow-up work such as:

- email
- analytics
- cache invalidation
- webhooks
- audit logging

Tasks must be **fast, idempotent, and failure-tolerant**.

---

## Correct shape

Background tasks should accept **identifiers or simple payloads only**
and load resources inside the task itself.

Example pattern:

```python
from fastapi import BackgroundTasks

@app.post("/users/{user_id}/welcome")
async def send_welcome(user_id: int, background_tasks: BackgroundTasks):
    background_tasks.add_task(send_welcome_email, user_id)
    return {"status": "scheduled"}

async def send_welcome_email(user_id: int):
    async with AsyncSessionLocal() as session:
        user = await session.get(User, user_id)
        if not user:
            return

        await email_service.send_welcome(user.email)
```

Background task functions must be `async def` when using async sessions. FastAPI runs async background tasks in the event loop, so this works without threads. For CPU-heavy or truly blocking work, use a real job queue instead.

Key properties:

- Task arguments are **IDs or primitives**
- The task **opens its own DB session**
- The task is **idempotent and failure-tolerant**
- Failures **must not affect request behavior**
- No retry logic is implemented inside the task

---

## Summary

Background tasks are **best-effort helpers**.

If the work must be **reliable or durable**, use a **real queue or job system**.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [robhowley](https://github.com/robhowley)
- **Source:** [robhowley/py-pit-skills](https://github.com/robhowley/py-pit-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-robhowley-py-pit-skills-background-jobs-boundaries
- Seller: https://agentstack.voostack.com/s/robhowley
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.