Work Queues

Work queues provide priority-based task assignment for agent teams. Tasks are dequeued by agents, support work stealing for load balancing, and track completion and failure status.

Creating queues and tasks

Tasks have a name, optional priority (1–5), payload, and deadline.

bash

# Create a work queue
curl -X POST http://localhost:3000/work-queues \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "bug-triage", "teamId": "engineering" }'

# Add a task to the queue
curl -X POST http://localhost:3000/work-queues/wq_abc123/tasks \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Investigate login timeout on mobile",
    "priority": 4,
    "payload": { "ticketId": "T-4821" },
    "deadline": "2026-03-08T17:00:00.000Z"
  }'

Dequeuing and work stealing

Dequeue assigns the highest-priority pending task to the requesting agent. Work stealing lets idle agents take tasks from other queues. Both return 204 if no tasks are available.

bash

# Dequeue the next task (assigns to agent)
curl -X POST http://localhost:3000/work-queues/wq_abc123/dequeue \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "triage-agent" }'

# Work stealing (take task from another queue)
curl -X POST http://localhost:3000/work-queues/wq_abc123/steal \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "idle-agent" }'

Completing and failing tasks

bash

# Complete a task
curl -X POST http://localhost:3000/work-queue-tasks/wt_abc123/complete \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "result": { "rootCause": "Session cookie SameSite attribute", "fix": "PR #312" } }'

# Fail a task
curl -X POST http://localhost:3000/work-queue-tasks/wt_abc123/fail \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "error": "Unable to reproduce on staging" }'

Endpoint reference

Method	Endpoint	Description
`POST`	`/work-queues`	Create queue
`GET`	`/work-queues`	List queues
`GET`	`/work-queues/:id`	Get queue
`DELETE`	`/work-queues/:id`	Delete queue
`POST`	`/work-queues/:id/tasks`	Add task
`GET`	`/work-queues/:id/tasks`	List tasks (filter by `status`)
`POST`	`/work-queues/:id/dequeue`	Dequeue next task
`POST`	`/work-queues/:id/steal`	Steal task
`POST`	`/work-queue-tasks/:id/complete`	Complete task
`POST`	`/work-queue-tasks/:id/fail`	Fail task