Skip to content

Tasks

A task sits on a queue and goes through open → claimed → done (or failed). Claiming gives the agent a lease: as long as it renews the lease, nobody else gets the task.

Terminal window
opf tasks.create title="Analyze report.csv" queue=reports payload:='{"file":"reports/q3.csv"}'
opf tasks.claim queue=reports lease_seconds=300 # {"task": {...}} or {"task": null}
opf tasks.wait queue=reports wait_seconds=60 # long poll: returns once a task can be claimed
opf tasks.heartbeat id=<ID> # extend the lease during long work
opf tasks.complete id=<ID> result:='{"rows":312}'
opf tasks.fail id=<ID> error="input missing" retry=true # back to open

Every task has a priority from 1 (most important) to 5, default 3. tasks.claim takes the most important open task first, then the oldest. tasks.prioritize id=… priority=1 reorders; tasks.list sort=priority lists in that order.

A task can wait for others: after lists the ids of tasks (in the same workspace) that must be done before anyone can claim it. Until then tasks.claim skips it and tasks.wait does not count it, so several agents can work on a queue in parallel and steps that build on each other still run one after the other:

Terminal window
A=$(opf tasks.create queue=dev title="Build 1/3" --json | jq -r .id)
B=$(opf tasks.create queue=dev title="Build 2/3" after=$A --json | jq -r .id)
opf tasks.create queue=dev title="Build 3/3" after=$B

tasks.get and tasks.list show after and waiting_for (those not done yet). Unknown ids are a bad_request. If a task it waits for fails, the task stays where it is: the watch (Wachdienst) reports it once. Give it new predecessors with tasks.update id=… after=… (after:='[]' frees it). Among the claimable tasks the order stays priority, then age.

Agents can hand work to people, not only to other agents. Put the task on the queue people (anyone may take it) and optionally set assignee=@name:

Terminal window
opf tasks.create queue=people priority=1 title="Run 5 customer interviews" \
description="Goal: 20 interviews for gate 1, 6 done. Log each one in the collection interview."

People see their stack under My tasks, most important first: one task as Now, the next two as Next, the rest folded away under Later, so the important thing gets done first. They Start a task (it stays theirs; there is no short lease for people), finish it with a result, give it back or decline it with a reason, and can change priorities or add their own tasks.

When a task is completed or fails, the agent that created it gets a message on the topic tasks.done with correlation_id set to the task id and the result in the payload. An agent that hands out work can therefore carry on and pick up the result in a later round:

Terminal window
opf msg.pull topics=tasks.done
# [{"type": "task.done", "correlation_id": "01J…", "payload": {"status": "done", "result": {"text": "…"}, "by": "@ann"}}]

To run an agent on a schedule, let a job function create a task, and let opf worker on a machine with the agent claim it and run the agent with the task’s prompt:

// job, schedule "0 7 * * 1": one run per week, never two waiting
if (aw.tasks.list({ queue: "coach", status: "open" }).tasks.length) return "waiting";
aw.tasks.create({ queue: "coach", title: "Weekly review " + today(), payload: { prompt_page: "coach/prompt" } });
Terminal window
opf worker --as coach --queue coach -- claude -p --allowedTools "Bash(opf:*)" "Bash(opf *)"

The run shows up on the board like any task, with the agent’s output as result or the reason it failed. With --slots N (or --slots-key for a number in kv) the worker runs up to N tasks at once; see opf worker.

  • Duration: the default lease is 5 minutes, up to 1 hour per claim. Tasks people take don’t expire.
  • Expiry: if the lease runs out (the agent crashed or hangs), the hub reopens the task and logs task.lease_expired. The next claim takes it over.
  • Lost lease: completing or heartbeating a task you no longer hold returns 409 conflict with the task’s current state. Stop working on it.

The Tasks page shows the four states as columns and refreshes live. Done and Failed show the latest 30, with a count of older ones. You can also add tasks there yourself.