Background Work

Do not block a chat turn on work that can run in the background. Capsule tasks and schedules keep that work inside the same app definition. Use tasks for work triggered by a user action. Use schedules for recurring work.

1. Define a task

@app.task(retries=2, timeout=300)
async def sync_leads(owner_id: str):
    # Talk to an API, update collections, write files, or run a model call.
    return {"synced": 10, "owner_id": owner_id}

Tasks are normal Python functions registered with the app.

2. Submit from chat

@app.message()
async def handle(session: cpsl.Session, msg: cpsl.Message):
    handle = await sync_leads.submit(owner_id=session.user.owner_id)
    await session.show_task(handle, message="Lead sync started")

show_task(...) renders a task card in chat so the user can see that work is running.

3. Show tasks on a page

@app.page("Tasks", icon="list-check")
def tasks_page():
    return cpsl.ui.Page(
        [
            cpsl.ui.TaskBoard(title="Background work"),
        ]
    )

Use this for operator visibility instead of hiding long-running work in logs.

4. Add a schedule

@app.schedule("0 * * * *")
async def hourly_sync():
    await sync_leads.submit(owner_id="system")

Schedules use cron strings and run inside the same app runtime model.

5. Add control

Task options help make background work production-shaped:

@app.task(
    retries=3,
    timeout=600,
    lock="owner:{owner_id}",
    process=True,
)
async def rebuild_index(owner_id: str):
    ...

retries handles transient failures.
timeout prevents runaway work.
lock avoids duplicate work for the same key.
process=True isolates CPU-heavy or crash-prone work.

Next steps

Deploy the app with Deploy An App.
See Tasks And Schedules.

Start Here

Build Apps

Features

Concepts

Updates

Background Work

1. Define a task

2. Submit from chat

3. Show tasks on a page

4. Add a schedule

5. Add control

Next steps

​1. Define a task

​2. Submit from chat

​3. Show tasks on a page

​4. Add a schedule

​5. Add control

​Next steps

1. Define a task

2. Submit from chat

3. Show tasks on a page

4. Add a schedule

5. Add control

Next steps