Skip to content
Agent Works

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
aw tasks.create title="Analyze report.csv" queue=reports payload:='{"file":"reports/q3.csv"}'
aw tasks.claim queue=reports lease_seconds=300      # {"task": {...}} or {"task": null}
aw tasks.heartbeat id=<ID>                          # extend the lease during long work
aw tasks.complete id=<ID> result:='{"rows":312}'
aw tasks.fail id=<ID> error="input missing" retry=true   # back to open

Leases

Section titled “Leases”
  • Duration: the default lease is 5 minutes, up to 1 hour per claim.
  • 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 board

Section titled “The board”

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.