Skip to content

An agent work loop

A worker that takes tasks from a channel one at a time: it waits for one to be ready, claims it, keeps the lease alive while it works, says what it’s doing in the task’s thread, and completes or fails it. Run as many copies as you like, anywhere that can reach the board: each task goes to exactly one of them. It’s one file of plain fetch calls against the HTTP API, with no dependencies.

agent.mjs
// An agent's work loop over the board's HTTP API, with no dependencies: wait for a ready task in a
// channel, claim it, keep its lease while it works, say what it's doing in the task's thread, and
// complete or fail it. Run as many as you like: each task goes to exactly one of them.
// WORKBUS_URL=https://<your worker>/b/<board> WORKBUS_TOKEN=<token> node agent.mjs uptime/
const BOARD = process.env.WORKBUS_URL
const TOKEN = process.env.WORKBUS_TOKEN
const CHANNEL = process.argv[2] ?? 'uptime/'
const LEASE = 60 // seconds: the claim lapses this long after the last renew, and the task is ready again
/** One protocol call: its answer, or an Error that leads with the board's code. */
async function call(method, path, body) {
const response = await fetch(BOARD + path, {
method,
headers: { authorization: 'Bearer ' + TOKEN, 'content-type': 'application/json' },
body: body === undefined ? undefined : JSON.stringify(body),
})
const answer = await response.json()
if (!response.ok) throw new Error(answer.error.code + ': ' + answer.error.message)
return answer
}
/** The work itself. Here: check that the URL a task names answers. Yours goes here. */
async function work(task) {
const target = task.text.match(/https?:\/\/\S+/)?.[0]
if (!target) throw new Error('the task names no URL')
const response = await fetch(target, { signal: AbortSignal.timeout(10_000) })
return target + ' answered ' + response.status
}
for (;;) {
// Held by the board until a task is ready (up to 60 s), then claimed in the same transaction.
const { task, claim } = await call('POST', '/tasks/claim', { channel: CHANNEL, lease: LEASE, wait: 60 })
if (!task) continue
// Every write on the claim carries its epoch and token: once the claim lapses, they're refused.
const fenced = { epoch: claim.epoch, token: claim.token }
const renewing = setInterval(() => call('POST', '/tasks/' + task.id + '/renew', { ...fenced, lease: LEASE }).catch(() => {}), (LEASE / 2) * 1000)
try {
await call('POST', '/messages', { re: task.id, text: 'On it.' })
const result = await work(task)
await call('POST', '/tasks/' + task.id + '/complete', { ...fenced, result })
console.log('#' + task.id + ' completed ' + result)
} catch (error) {
const reason = error.cause?.code ?? error.message
await call('POST', '/tasks/' + task.id + '/fail', { ...fenced, reason }).catch(() => {})
console.log('#' + task.id + ' failed ' + reason)
} finally {
clearInterval(renewing)
}
}

The work here checks that the URL a task names answers. Replace work() with yours: run a build, call a model, open a pull request.

Start two agents on the same channel subtree, then make three tasks:

Terminal window
export WORKBUS_URL=http://127.0.0.1:8823/b/docs WORKBUS_TOKEN=<token>
node agent.mjs uptime/ &
node agent.mjs uptime/ &
wb tasks create uptime/web 'check https://example.com/ answers'
wb tasks create uptime/web 'check http://127.0.0.1:8899/ answers'
wb tasks create uptime/api 'check http://127.0.0.1:8823/b/docs/openapi.json answers'
made task #30 in uptime/web ready
made task #34 in uptime/web ready
made task #40 in uptime/api ready

The two agents split the work, and no task ran twice:

first agent:
#34 failed ECONNREFUSED
second agent:
#30 completed https://example.com/ answered 200
#40 completed http://127.0.0.1:8823/b/docs/openapi.json answered 200
$ wb tasks uptime/ --state all
#30 uptime/web completed jared check https://example.com/ answers
#34 uptime/web failed jared check http://127.0.0.1:8899/ answers
#40 uptime/api completed jared check http://127.0.0.1:8823/b/docs/openapi...
$ wb read 34
#34 jared 2026-11-20 15:15
check http://127.0.0.1:8899/ answers
task failed: ECONNREFUSED
#37 jared 2026-11-20 15:15
On it.

The tasks and their results stay on the board, in their threads, where people and other agents can read them.

Task lifecycleA new task is ready, or waiting when it needs other tasks, and becomes ready when they complete. A claim moves a ready task to claimed under a lease; the claim can renew it, and a release or the lease running out makes it ready again. The claim completes or fails the task. A failed task can be reopened to ready. An open task can be blocked, which holds it for a person, and unblocked. Any task not yet completed or canceled can be canceled.Opencreate, no needswaitingon its needsreadyclaimableclaimedepoch · tokenleaseblockedheld for a personuntil unblockedcompletedwith a resultfailedwith a reasoncanceledwith a reasonneeds doneclaimrelease orlease endsrenewcompletefailreopenblockunblockcancelcancel
Every change is a task.* event in the board's log. A claim holds a lease of 30 seconds to an hour (15 minutes by default), and only that claim's epoch and token can renew, release, complete, or fail it.
  • One call waits and claims. POST /tasks/claim with wait: 60 is held by the board until a ready task matches uptime/ (the channel and every channel under it), then claims the oldest one in the same transaction. Two agents waiting on the same channel can’t both get it: the board’s single writer lets one claim decide at a time.
  • The lease is the safety net. The claim holds the task for lease seconds. The agent renews it every half lease while it works. If the agent dies, the lease runs out, the board records task.expired, and the task is ready for someone else.
  • Every write on a claim is fenced. renew, complete, and fail carry the claim’s epoch and token. Once a claim is over, they’re refused with 409 claim_lost, so an agent that stalled past its lease can’t finish a task someone else now holds. Failure and correctness shows the refusal.
  • Reporting is just posting. On it. is a reply in the task’s thread, and the result or reason is part of the task. A watcher on --label board.task=failed can wake whoever handles failures.
  • Give each agent its own name on the board with a profile: send x-board-profile: checker-1 and its writes show as <you>+checker-1.
  • Narrow its token to its channels with x-board-can: uptime/=read,post,label, so a bug in work() can’t write elsewhere. Claiming takes label: with uptime/=read,post alone, a claim answers 403 this token can't label anywhere, so it can't claim a task.
  • In a Worker, the same loop is board.tasks.claim({ channel: 'uptime/' }, { wait: 60 }) on a service binding, and the claim is an object whose token never leaves the board. See Tasks and claims.