8. Background jobs and handles¶
Some work is too slow for one call, and some results are too large for one context. Step 5 adds a circulation report for librarians that has both problems: it reads every book at the branch, and it returns a row per book.
Turning handles on¶
handles=True adds two small tools:
| Tool | Does |
|---|---|
jobs.get |
Reports a job's state and, when it is done, its summary and a handle to its rows |
handles.read |
Reads a stored result a page at a time |
A job¶
@server.job("reports.circulation", max_attempts=3)
async def circulation(args: ReportArgs) -> JobResult:
library: Library = server.deps
books = [b for b in library.books.values() if b.branch == args.branch]
rows = [
{"book_id": b.id, "title": b.title, "on_loan": b.copies - library.available(b.id)}
for b in books
]
busiest = max(rows, key=lambda r: r["on_loan"], default=None)
summary = Circulation(
branch=args.branch,
books=len(rows),
on_loan=sum(r["on_loan"] for r in rows),
busiest=busiest["book_id"] if busiest and busiest["on_loan"] else None,
)
return JobResult(summary=summary, items=rows)
@server.tool(name="reports.start", effect=Effect.READ, policy=require_scopes("librarian"))
async def start_report(ctx: ToolContext) -> ReportStarted:
"""Start the circulation report for your branch (librarians only), then poll
jobs.get with the job id. Read the per-book rows with handles.read."""
job = await ctx.start_job("reports.circulation", {"branch": member(ctx)[1]})
return ReportStarted(job=job, message="Report started. Check it with jobs.get.")
The job is a plain async function registered by name with @server.job. It takes a Pydantic model of arguments and returns a JobResult: a small summary the model reads directly, and the items, stored behind a handle.
The tool that starts it returns at once with a job id:
- The model calls
reports.startand gets{"job": "...", "message": "Report started. Check it with jobs.get."}. - It calls
jobs.getwith the id. While the job runs, the state isrunning; when it finishes,done, with the summary inresult, the number of rows initemsand ahandle. - If it needs the rows, it calls
handles.readwith the handle, a page at a time.
The summary for the north branch fits in a few dozen tokens; the 30 rows never enter the context unless the model asks for them.
Surviving a restart¶
Because the job is registered by name and started as ctx.start_job("reports.circulation", args), its name and arguments are saved in the store. If the process running it stops, the next jobs.get, on any replica that shares the store, starts it again, up to max_attempts times. A job should therefore be safe to run twice: read, compute, and write through idempotent operations.
For a one-off background task that does not need to survive a restart, pass a coroutine function instead: await ctx.start_job(work).
Handles without jobs¶
A tool that already has a large result can store it and return a handle straight away:
Handles, like cursors, are signed and bound to the tenant that created them, and they expire. Another branch cannot read your report by guessing or reusing its handle.
Summary¶
handles=Trueaddsjobs.getandhandles.read.- Register slow work with
@server.job(name)and start it withctx.start_job(name, args); it restarts after a crash. - Return a small summary for the model and keep the rows behind a handle.