Task Queue

When to useCopy Anchor Link

• The agent has several separate tasks lined up to run one after another, and the user may want a say in the order.
• The user asks what the agent is working on next, or to change the order, pause or drop something it queued.

When not to useCopy Anchor Link

• It's the steps of one job running now. Use Execution Progress.
• The tasks are for the user to do. Use a Checklist or the Todo List.
• Work items move between stages on a team board. Use a Kanban Board.
• There is only one task. Do it, or ask.

How the agent should use itCopy Anchor Link

• Pass every task from the runtime with its real state (running, waiting, done, failed), and keep ids stable as states change.
• List waiting tasks in run order. Give each a short detail such as "~4 min · 9 accounts".
• Add progress (0–1) to a running task that can measure it, and a plain error to a failed one.
• Turn off what the runtime can't do with canReorder, canPause or canCancel: false.
• Treat every result as a command: act on it, then send updated props. The component never assumes a command was applied.
• On approve, run the waiting tasks in exactly the returned order. After pause, show the task as waiting again.

InteractionCopy Anchor Link

• Working now shows the running task with a spinner, its progress and Pause and Cancel buttons.
• Up next is a numbered list. Each row has Move up, Move down and Cancel buttons (44px targets, labelled with the task and its position); focus stays on the moved task and each move is announced.
• Approve order sends the order the user settled on; Reset order appears once it differs from the agent's. After approving, the order locks and a record takes focus.
• Pause and cancel mark the task "Pausing…" or "Cancelling…" until the host sends its new state. A task being cancelled is left out of an approved order.
• Failed tasks stay in view with their error; finished ones fold under Finished. While streaming, tasks arrive one by one and controls are disabled.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/task-queue.json

UsageCopy Anchor Link

import { tool } from "ai"
import { taskQueueTool } from "@/components/genui/task-queue.schema"

const tools = {
  [taskQueueTool.name]: tool({
    description: taskQueueTool.description,
    inputSchema: taskQueueTool.inputSchema,
  }),
}

import { TaskQueue } from "@/components/genui/task-queue"

function ToolPart({ part, addToolResult }) {
  if (part.type !== "tool-show_queue") return null

  return (
    <TaskQueue
      {...part.input}
      status={part.state === "input-streaming" ? "streaming" : undefined}
      result={part.state === "output-available" ? part.output : undefined}
      onResult={(result) =>
        addToolResult({
          tool: "show_queue",
          toolCallId: part.toolCallId,
          output: result,
        })
      }
    />
  )
}

The result is one command:

{ action: "approve", order: ["deck", "renewals", "links", "invoices"] }
{ action: "pause", taskId: "tickets" }
{ action: "cancel", taskId: "links" }

SchemaCopy Anchor Link

Host props: status (streaming, ready), onResult, result and className.

SourceCopy Anchor Link