Queues

A backlog with one drain

Each queue is bound to exactly one deployed agent and carries a name, an optional description, a status and a concurrency setting. Items are dispatched in the order they were enqueued: the sweep always promotes the lowest-position pending item, and overlapping sweeps cannot claim the same item twice.

Concurrency is how many items may run side by side. It accepts 1 through 20 and defaults to 1. Each parallel slot is a parallel billed agent session, so raising it multiplies spend as well as throughput.

Create once, push often

Create the queue against a deployed agent, then push payloads onto it. A single enqueue returns the item id and its position in line; the batch form takes up to 500 payloads and appends them in order. Both fail if the queue is paused or archived, and the batch fails atomically, so a rejected batch leaves nothing half-enqueued.

// one queue, bound to one deployed agent
agnt_queues_create({
  agent_id: "<deployed agent uuid>",
  name: "Inbound demo requests",
  concurrency: 3
})

// push work onto it, one item at a time…
agnt_queues_enqueue({
  queue_id: "<queue id>",
  payload: { company: "acme.com", source: "webinar" }
})

// …or up to 500 in a single call
agnt_queues_enqueue_batch({
  queue_id: "<queue id>",
  payloads: [{ company: "acme.com" }, { company: "globex.com" }]
})

Agents can fill a queue themselves, which is the usual way one agent hands work to another: a scraper enqueues one item per row it found, and the bound agent works the list down. The platform records which deployed agent enqueued each item, so attribution survives even when several producers share one queue.

Four states, one session each

An item starts pending, flips to processing when the sweep claims it, and lands on completed or failed. A failure does not stop the queue: the item keeps its error string and the drain moves on to the next one.

Depth, drain and the failing item

The workspace Queues page shows each queue as a row with a completed / processing / pending / failed breakdown, how far it has drained, a pause and resume control, and a link into the queue detail page. It also rolls the workspace up: total in flight across every queue, and total failed items.

From an MCP client, agnt_queues_list returns every queue with its pending and processing counts, which is the cheap check before you push more work. agnt_queues_list_items reads the items themselves, filtered by status and paged with a position cursor. Use agnt_queues_update to rename, re-concurrency or move the status.