Queue

Introduction

Queue is a queue-based work item system for agents. It lets you feed individual work items — called cases — into a queue, where agents automatically pick them up, process them, and report results. This is useful when you have a stream of tasks that need to be handled one at a time (or in parallel), such as processing incoming requests, handling tickets, or working through a batch of items.

Key Concepts

A queue is a container that holds cases waiting to be processed. Each team has one default queue, and cases flow through it to be claimed by agents.

Case

A case is an individual work item with a title and associated data. Think of it as a task card — it carries the information an agent needs to do its work.

Case Statuses

Status	Meaning
Pending	Waiting in the queue to be picked up, or held back while a Connection the agent needs is missing or needs reconnecting
In Progress	An agent has claimed the case and is working on it
Needs Input	The agent is waiting for a human response before continuing
Postponed	Waiting until a scheduled time before being picked up again
Completed	The agent marked the case done, or Duvo auto-closed an unresolved case after a clean Run
Failed	The agent marked the case failed, or the Run for an unresolved case errored, was cut off mid-work, or had its handover rejected
Canceled	A team member or the API stopped the Run that was working on the case

Agent Triggers

An agent trigger connects an agent to a queue. When a new case arrives, the trigger automatically dispatches the agent to claim and process it — no manual intervention needed.

How It Works

Cases are added to a queue

Either by another agent or by an external system via the API.

An agent with a case trigger claims the next case

The agent automatically claims the next pending case.

The agent processes the case

The agent uses the case data as input.

The case is resolved

The agent marks the case as completed, failed, or postponed, or requests a handover. If the case is still unresolved when the Run ends, Duvo settles it itself — completed when the Run finished its work cleanly, failed when the Run ended with an error, was cut off mid-work, or had a handover rejected.

Status Transitions

Case statuses follow a specific lifecycle. Understanding these transitions helps you write better AOPs and troubleshoot processing issues.

Pending → In Progress: When an agent picks up a case from the queue, the case moves to In Progress. This happens automatically through the case trigger — the agent claims the next available case and begins working on it.

A case stays Pending while a Connection the agent needs is missing or needs reconnecting. Duvo does not hand the case to the agent, because the Run would fail before it could do any work and the case would be settled as Failed. Add the missing Connection, or reconnect the broken one, and the queue picks the case up on its own — nothing to retry.

In Progress → Needs Input: If the agent requires human input while processing (via the Human-in-the-Loop feature), the case shows as Needs Input until the human responds.
In Progress → Completed: The agent explicitly marks the case as completed after it finishes processing successfully. Your AOP should instruct the agent on when and how to mark a case as done. A Run that finishes its work cleanly but never resolves the case also lands here: Duvo closes the case as Completed rather than assuming it failed, and leaves the real result to the automatic evaluation. The case activity marks it as auto-completed, but carries no explanation from the agent — so a case that should have been failed or postponed looks resolved until the evaluation flags it.
In Progress → Failed: The agent explicitly marks the case as failed, or its Run ends with an error, is cut off mid-work, or requests a handover that is rejected, with the case still unresolved. An automatic failure carries no reason at all. Whenever Duvo settles a case for you like this — Completed or Failed — it is guessing on your behalf, so your AOP should always instruct the agent to explicitly resolve each case.
In Progress → Canceled: A team member or the API stops the Run while it is working on the case. A deliberate stop is not a failure, so the case is canceled rather than failed — retry it when you want the work done.
In Progress → Postponed: The agent can postpone a case to delay processing until a later time. This is useful when the agent determines that a case needs to wait — for example, waiting for an external event, a cooling-off period, or a specific business hour. The agent specifies when the case should be retried, either as a specific time or a relative duration (e.g., “2 hours”, “1 day”). When the postponed time arrives, the case is automatically dispatched for processing again.

Writing AOPs for Case Processing

The agent decides how to handle a case based on your AOP instructions. To get reliable results, your AOP should clearly tell the agent:

When to complete a case — define what “done” looks like. For example: “After sending the reply email, mark the case as completed.”
When to fail a case — define what counts as unprocessable. For example: “If the customer account cannot be found, update the case with the reason and mark it as failed.” Note that if the Run ends with the case still unresolved, Duvo settles it for you — as Completed after a clean finish, as Failed after an error, a Run cut off mid-work, or a rejected handover — with no explanation of the work. Explicitly failing with a reason is always preferred so you can review what went wrong.
When to postpone a case — define conditions for delaying. For example: “If the report data is not yet available, postpone the case for 2 hours.”

Without clear instructions, the agent may not resolve cases properly. Duvo then settles them for you — Completed or Failed, depending on how the Run ended — without an explanation, so you lose the record of what the agent actually decided.

Setting Up Queue in the Builder

Queue is configured directly from the agent builder. A dedicated Queue section appears in the builder header, separate from Connections, where you link the agent to the queues it should read from or write to. To connect an agent to one or more queues:

Open your agent in the builder

Open the agent you want to link to a queue.

Open the Queue Setup dialog

In the Queue section of the builder header, click the plus button. This opens the Queue Setup dialog.

Choose how the agent interacts with each queue

In the dialog, choose how the agent should interact with each queue:

Processes Cases (Consumer) — the agent picks up and processes cases from the selected queue.
Adds Cases (Producer) — the agent adds new cases to the selected queue.

If your team has more than 20 queues, a search box appears at the top of the dialog so you can filter by name.

Configure trigger controls (live revision)

On a live revision, after selecting a consumer queue, trigger controls appear inside the dialog. You can enable the case trigger and set concurrency here alongside your queue selection. Changes are saved together when you click Save.

Choose sequential or parallel processing

After selecting a consumer queue, choose whether Cases in that Queue are processed sequentially (one at a time) or in parallel (the default). This setting applies to the whole Queue and is shared across every Agent working it, not to one Agent alone. Pick sequential when Cases must not overlap — for example, when they touch the same record or external system.

A single agent can act as both a producer and a consumer if needed — just link the relevant queues under each role in the dialog.

Enabling the Case Trigger

Linking a queue as a consumer lets the agent access that queue, but it will not start processing cases until the case trigger is enabled. You can manage the case trigger from three places:

Queue Setup dialog
Schedule & Triggers panel
CLI

Recommended when setting up for the first time.

Open the Queue Setup dialog

Open the Queue Setup dialog from the builder header.

Select a consumer queue

Select a queue under Processes Cases (Consumer).

Enable Runs on new cases

Enable Runs on new cases to start automatic processing.

Optionally restrict concurrency

Optionally enable Process cases one at a time to restrict the Queue to one Case at a time instead of in parallel. This limit applies to the whole Queue, shared across every Agent working it.

Save

Click Save — queue setup and trigger settings are saved together.

If another agent is already consuming the same queue with an active trigger, a conflict warning appears and Save is blocked until you resolve it. Only one agent can hold an active trigger on a given queue at a time.

For scripting and automation.You can also enable or disable the case trigger from the command line. First find the trigger ID with duvo agents case-triggers list <agent-id>, then toggle it:

duvo agents case-triggers update <agent-id> <trigger-id> --enable
duvo agents case-triggers update <agent-id> <trigger-id> --disable

Only the person who set up a trigger or a team Builder or admin can disable it. For the full set of trigger commands — create, delete, switch queues, set concurrency — see Scheduling and Triggers.

Once the trigger is enabled, the agent will start claiming and processing cases as they arrive in the linked queue.

Producer and Consumer Pattern

A common pattern is to have one agent create cases and another process them:

Producer agent: Runs on a schedule or trigger, identifies work items, and adds them as cases to the queue.
Consumer agent: Has a case trigger enabled and automatically picks up and processes each case.

This separation keeps your workflows modular — the producer focuses on identifying work, while the consumer focuses on doing it.

Adding large batches of cases

A producer agent can hand add_cases its cases in one of two ways: inline, or as a file. For large batches, always use the file.

Inline — the agent writes the case array directly into the tool call. Fine for a handful of cases.
From a file — the agent writes the complete case array to a JSON file in its workspace and passes that path instead. Nothing is retyped, so nothing can be lost on the way into the queue.

A single case can do the same with its data: point at a workspace file rather than pasting a large payload into the case. If your AOP asks a producer to build a big batch, tell it to write the cases to a file first. When a batch cannot be added, the run now fails with a clear error instead of quietly creating one malformed case.

Files that are not UTF-8

Case files are read as UTF-8. If your source files use a different character set — for example Windows-1250 order exports from an ERP — the agent must declare it when adding the cases, or convert the files to UTF-8 first. A batch file declares its character set with cases_file_encoding (for example cases_file_encoding: "windows-1250"), and a single case’s data file uses data_file_encoding. The value is the exact lowercase label, so "Windows-1250" or "UTF-16" are rejected in favour of "windows-1250" and, for UTF-16, whichever of "utf-16le" or "utf-16be" matches the file’s byte order. The queue rejects a file whose bytes are not valid text in the character set it was read with, and rejects text that already contains the � replacement character. That catches the common case where a non-UTF-8 file is read as UTF-8. It cannot catch a wrong declaration: the same bytes are often valid text in several character sets, so declaring Windows-1252 for a Windows-1250 file yields readable but incorrect characters (pìna instead of pěna) that no automatic check can distinguish from correct text. So the character set has to be declared correctly, and the reliable place for that is the AOP: tell the producer which character set its source files use, or have it convert them to UTF-8 during ingestion. If you see garbled characters in case data, that declaration is what to fix.

Case Labels

Cases can be tagged with labels to organize and categorize your work. Labels appear as Key: Value pills in the case detail header, making it easy to see how a case has been classified at a glance. Labels are scoped to the queue — when adding a label, an autocomplete popover shows labels already used in that queue, making it easy to apply consistent classifications across cases.

Managing Labels

Assign a label — Open the case detail and click the attributes area. Select an existing attribute and one of its values to apply a label. To create a new label type, enter a new attribute name to add it as a draft, then add values to it — the first saved value promotes the attribute from draft to active.
Remove a label — Click the × on a label pill to remove it from the case.
Rename a label — Click the label text to enter inline edit mode. Update the key or value and press Enter to save, or Escape to cancel.

Agents can also assign labels automatically using the assign_labels tool in their AOP. This lets cases be categorized as part of automated processing — for example, tagging a case with Priority: High or Type: Escalation before completing or handing it over.

Case Priority

Cases can be given a priority so that important work is picked up first. Priority is optional — by default a case has no priority, and most cases stay that way. There are three levels:

Priority	Meaning
No priority	The default. Cases are handled in the order they arrived.
Medium	Handled ahead of default-priority cases.
High	Handled ahead of medium- and default-priority cases.

When a consumer agent picks up its next case, it takes the highest-priority case first, and within the same priority the oldest case first. Postponed cases that are due are still handled ahead of priority, so raising priority never overrides a scheduled wait. A High priority or Medium priority badge appears before the case title in the Cases list and on the case detail view. Default-priority cases show no badge, keeping the list uncluttered.

Setting priority

You can change a case’s priority at any time:

A single case — open the row actions menu (three-dot icon) and choose Set priority, or open the case detail view and use the priority control in the header. Choose High, Medium, or No priority (to clear it).
Multiple cases — select cases with the checkboxes, then click Set priority in the bulk actions bar and choose a level. This works with select-all-matching too.

Changing priority never interrupts a Run or changes a case’s status — it only affects the order pending cases are picked up in.

Priority when creating cases

Producer agents can set a priority when adding cases with the add_cases tool, and the public API accepts a priority when creating cases. Agents should only set a priority when your AOP or a person has explicitly asked for that kind of case to be prioritized — otherwise cases are created with no priority.

Raising priority reorders work; it does not add capacity. If you flood a queue with high-priority cases, everything is high priority and normal cases can wait indefinitely behind them.

Retrying and Updating Cases

You can manually retry or update cases from both the Cases list and the case detail view.

Retry — Cases in Completed, Failed, In Progress, or Needs Input status can be retried. This resets them to Pending — any active Run is stopped first — so they are picked up and processed again. This is useful when a case failed due to a temporary issue, when you want to reprocess a case after updating your agent’s AOP, or when you need to restart a Run that is stuck or waiting for input.
Mark as Completed — Manually mark any non-completed case as Completed. Useful when a case was resolved outside the agent workflow.
Mark as Failed — Manually mark any non-failed case as Failed. Use this to close out cases that are no longer relevant or cannot be processed.

To update a case, open the case detail view and click the status badge to open the status dropdown.

Delegating Cases to Specific Agents

You can manually send one or more cases to a specific agent, bypassing the queue’s automatic trigger. This is useful when a case needs to be handled by a particular agent — for example, routing to a specialist or re-processing with a different agent after a failure.

Delegating a single case

Open the row actions menu (three-dot icon) on any case and choose Delegate. A dialog opens listing all agents connected to the queue as consumers. Agents with their case trigger enabled are labelled Default; those with the trigger disabled are labelled Standalone. Select the target agent and confirm.

Delegating multiple cases

Select the cases you want to delegate using the checkboxes, then click Delegate in the bulk actions bar that appears. Choose the target agent in the dialog and confirm. Delegation immediately dispatches a Run on the target agent for each selected case, regardless of the queue’s automatic trigger settings.

Human-in-the-Loop with Cases

Cases work with the Human-in-the-Loop feature. If a consumer agent needs human input while processing a case, it will pause and send a notification to Requests. The case shows as Needs Input until the human responds and the agent completes its work. For guidance on designing escalation patterns, managing Needs Input backlogs, and ramping toward safe autonomy in queue-based workflows, see Designing Human-in-the-Loop Workflows.

Organizing Queues

If your team has many queues, you can organize them into folders in the sidebar. Folders help you group related queues together and keep the sidebar manageable as your workload grows.

Creating folders

To create a folder, click the + icon next to the Queues heading in the sidebar and choose New folder. Give the folder a name and save it.

Moving queues into folders

Drag any queue and drop it onto a folder to move it inside. You can drag from either the sidebar or the main queue overview. A highlighted ring and background on the folder indicate a valid drop target. To move a queue back to the top level, drag it onto the Queues area above all folders. Drag operations require queue management permissions. If you cannot drag a queue, check that your role has permission to manage queues for the team.

Queue Statistics

The Queues overview page shows a statistics bar for each queue — a count of cases broken down by status (Total, Pending, Postponed, In Progress, Needs Input, Completed, Failed). These stats help you understand throughput and failure rates at a glance. Use the time period selector (top-right of the overview) to filter statistics to a specific window: All time, Last hour, Last day, Last 7 days, Last 30 days, or Last year. Selecting a period filters the Completed and Failed counts to only cases resolved within that window, so you can see recent throughput rather than all-time totals.

Viewing Cases

You can monitor your queue from the Cases page in your team space:

Label columns — Each label group appears as its own column in the cases table, showing the assigned value as a colored chip for every case that has it. This lets you scan and compare label values across cases at a glance without opening each one.
Filter by status — Show only cases in a specific status: Pending, In Progress, Needs Input, Postponed, Completed, or Failed.
Filter by priority — Show only cases at a chosen priority level: High, Medium, or No priority.
Filter by labels — Click the Filters button to open the filter dropdown and select one or more label values. Only cases carrying all selected labels are shown. Active filters appear as chips above the table; click the × on any chip to remove it.
Filter by date — Narrow the list to cases created within a specific date range.
Search cases by title keyword to find specific items in a large queue.
Sort cases by date created, last updated, or postponed time — newest first by default.
Browse pages of results when your queue has many cases (20 per page by default, up to 100).
View case details including title, data, and processing history.
Track queue stats to understand throughput and failure rates.

Filter state is reflected in the page URL, so you can copy and share a filtered view with teammates. Agents that list cases via the list_cases tool can also filter by label values, priority, and a created date range, making it easier to process only a specific subset of cases.

Case Files

A case can carry the documents it is about — the original invoice as a PDF or EDI file, a statement, a scanned form. Keep the source document on the case, so anyone reviewing it can check the outcome against the document it came from. Files appear in the Files section of the case detail view, oldest first.

Add a file as a teammate

Requires permission to manage the queue.

Open the case detail view.
Click Attach file in the Files section.
Choose a file. It appears in the list once the upload completes.

Agents and case files

Agents work with case files through two tools:

attach_case_file attaches a file from the Agent’s workspace — the invoice it fetched, or a document it produced. The file stays readable on the case after the Run finishes.
read_case_file downloads a case’s file into the Agent’s workspace. An Agent that picks up a case can open a document attached by a teammate or an earlier Run — the file travels with the case, not with any one Run.

View, download, or remove a file

Select View on a file to open it in the built-in viewer. Images and text-shaped documents (CSV, TSV, EDI, XML, JSON, Markdown, plain text) render in place, so you can read an invoice without downloading it. PDFs open in a new browser tab from the viewer. Office documents and archives can’t be shown in the browser, so those offer download only.
Select Download on a file to save it and open it on your device. Any file that uploaded successfully can be downloaded.
A teammate who can manage the queue can remove a file. Removal asks for confirmation first — it can’t be undone, and Agents working the case can no longer open the file.

Supported types

PDF, images, CSV/TSV, EDI, XML, JSON, text, Word and Excel documents, and ZIP archives. Executables and browser-executable markup are rejected.

A case holds up to 25 files of up to 50MB each.

A file that fails to upload stays visible and says so. It is listed with the reason it failed rather than quietly disappearing — a case missing its source document must not look like a case that never had one. The same applies to an upload that never finishes, from a closed tab or an interrupted Run: once its upload window has passed it is shown as failed, not as still uploading, and its slot is reclaimed so it can’t block the case. A failed file offers no download, because there are no bytes to download.

Attaching, removing, and failed attachments are all recorded in the case’s activity timeline.

Case Handover

An agent can hand a case off to another agent during processing. When the agent determines that a different specialist should handle the case, it requests a handover instead of completing or failing the case. The case is released and routed to the target agent, which picks it up and continues processing. This is useful for triage workflows where a general agent routes cases to specialists, or for escalation paths where routine cases are handled by one agent and complex ones are escalated to another. The case timeline in the case details view shows which agent handled each stage. For setup instructions and setup details, see Agent Handover.

Managing Queues and Cases via API

Queues and cases can be created and managed programmatically using the Duvo Public API. This is useful for provisioning queues, feeding cases from external systems, or triggering processing as part of automation pipelines.

Queue operations

List queues — retrieve all queues for your team
Create a queue — provision a new queue with a name and description
Get a queue — fetch details for a specific queue
Update a queue — rename or update a queue
Delete a queue — remove a queue

Creating cases via API

You can add cases to a queue directly from an external system using the public API. This is useful when your source of work items lives outside Duvo — for example, a webhook from a CRM, a record created in a database, or the output of a batch job. Endpoint: POST /queues/{queue_id}/cases You can create a single case or up to 100 cases in one request: Single case:

{
  "case": {
    "title": "Invoice #12345",
    "data": { "invoice_id": "12345", "amount": 1500 }
  }
}

Batch (up to 100):

{
  "cases": [
    { "title": "Invoice #12345", "data": { "invoice_id": "12345" } },
    { "title": "Invoice #12346", "data": { "invoice_id": "12346" } }
  ]
}

Each case also accepts an optional priority (none, medium, or high). Use medium or high to raise it above default-priority cases in the queue; omit it or pass none for normal priority. Cases created via the API are added as Pending and, if a consumer agent has a case trigger enabled, will be dispatched automatically. For authentication and general API usage, see Running Agents via API.

Key Takeaway

Queue gives your agents a structured way to receive and process work items. Pair it with agent triggers for fully automated processing, or use the producer-consumer pattern to build modular, scalable workflows.

​Introduction

​Key Concepts

​Queue

​Case

​Case Statuses

​Agent Triggers

​How It Works

​Status Transitions

​Writing AOPs for Case Processing

​Setting Up Queue in the Builder

​Enabling the Case Trigger

​Producer and Consumer Pattern

​Adding large batches of cases

​Files that are not UTF-8

​Case Labels

​Managing Labels

​Case Priority

​Setting priority

​Priority when creating cases

​Retrying and Updating Cases

​Delegating Cases to Specific Agents

​Delegating a single case

​Delegating multiple cases

​Human-in-the-Loop with Cases

​Organizing Queues

​Creating folders

​Moving queues into folders

​Queue Statistics

​Viewing Cases

​Case Files

​Add a file as a teammate

​Agents and case files

​View, download, or remove a file

​Supported types

​Case Handover

​Managing Queues and Cases via API

​Queue operations

​Creating cases via API

​Key Takeaway

Introduction

Key Concepts

Queue

Case

Case Statuses

Agent Triggers

How It Works

Status Transitions

Writing AOPs for Case Processing

Setting Up Queue in the Builder

Enabling the Case Trigger

Producer and Consumer Pattern

Adding large batches of cases

Files that are not UTF-8

Case Labels

Managing Labels

Case Priority

Setting priority

Priority when creating cases

Retrying and Updating Cases

Delegating Cases to Specific Agents

Delegating a single case

Delegating multiple cases

Human-in-the-Loop with Cases

Organizing Queues

Creating folders

Moving queues into folders

Queue Statistics

Viewing Cases

Case Files

Add a file as a teammate

Agents and case files

View, download, or remove a file

Supported types

Case Handover

Managing Queues and Cases via API

Queue operations

Creating cases via API

Key Takeaway