Queues and concurrency

Control which runs can proceed together, what happens when a key is busy, and when to debounce.

A queue limits how many runs proceed at once for the same key. Most agents can start without one. Add a queue when concurrent work could overwrite a shared record or overwhelm a service.

Choose a key and busy behavior

Example	Key	Runs at once	When busy
Update one customer record safely	Input field `customer_id`	1	Wait. Other customers can proceed independently.
Prevent overlapping nightly reports	One fixed key for every run	1	Skip a new start if the previous report is still running.
Bound use of a shared external service	One fixed key on a shared queue	A limit appropriate to that service	Wait. This limits runs, not every individual request a run might make.
Summarize the latest document revision	Input field `document_id`	1	Replace still-waiting work with the newest request.
Allocate concurrency per app user	The app user the run is for	A per-user limit	Wait; optionally cap how many may wait.

Replacing waiting work does not cancel work already running. If you want to wait for a burst of edits to settle before any work begins, also configure debounce.

Create and assign a queue

Owners and administrators create and manage queues in the environment. Choose the key strategy, concurrency, busy behavior, and a maximum waiting count if needed.

On a published agent or workflow, use Queue → Change… to assign a queue. Builders can select this assignment, and it takes effect immediately. A queue can also be chosen during publication. A new version keeps its queue unless another is selected.

Test the key using representative input. Two runs using the same key should share the limit; runs with different keys should have independent capacity within the platform's other limits.

Understand what holds a place

Active work holds a place, including time spent on its own workers and workflow steps.
Waiting for a person, external event, or timer releases the place. The run acquires one again when it continues.
Work requiring review of an uncertain external action keeps its place until the outcome is settled. Starting another action on that same record could compound the uncertainty.
Pausing the queue stops new runs from starting in it. Already-running work continues.

Inspect Now to see active and waiting runs. A waiting run's page shows its position and which work is ahead. A queue can be working correctly even when there are no free places; first check the key and the run holding it.

Queue, debounce, or run limit?

A queue controls concurrency across runs. Debounce folds repeated starts with the same key into one. An agent's turn, tool-call, and timeout limits bound the work inside one run. None substitutes for the others.

See Schedules and triggers for automated starts and Configure an agent for per-run limits.