Skip to main content
Use @agentium/queue when a request should enqueue work and return a job ID while a separate worker runs an agent, team, or workflow. Producers and workers share Redis and a queue name; the worker owns the executable registry.

Run one job

This example uses a deterministic model to exercise delivery without a provider account. Use Node.js ^22.18.0 or ^24.11.0 and a running Redis instance.
1

Install the package and queue peers

2

Start Redis for local development

Use your existing development Redis, or run a disposable container:
Keep Redis running in that terminal. The example defaults to redis://127.0.0.1:6379; set REDIS_URL to use another instance.
3

Save background-job.ts

background-job.ts
4

Run it in another terminal

Expected output:
The example waits up to 30 seconds for the job result, removes its completed demo record, and closes the worker, producer, and agent. Stop the Redis container when finished.

Use a real model

Replace the deterministic provider with a provider from the model catalog. For example, install openai, set OPENAI_API_KEY, import openai from @agentium/core, and use model: openai(process.env.OPENAI_MODEL ?? "gpt-6.1-sol") in the Agent constructor.

Split producer and worker

The single-file example makes the first run easy to verify. In an application, the API process normally owns AgentQueue and worker processes own AgentWorker. The enqueued name must exactly match a registry key in the worker. All three payloads can carry sessionId, userId, and tenantId. Derive those values from trusted application state before enqueueing; the queue does not authenticate a user.

Choose the right recovery model

Ordinary queue retries execute the job again. They can repeat model calls and tool side effects. Configure retry behavior on the producer and make effects idempotent where needed. Durable delivery connects queue hints to persisted task state and explicitly recoverable drivers. It is a separate execution contract, not a flag that makes an ordinary Agent run replay-safe. BullMQ ^5.81.5 and ^6.3.11 are supported. Existing repeat records need the schedule migration before upgrading to v6.

Enqueue and inspect jobs

Retries, delays, results, removal, and producer cleanup.

Operate workers

Registries, concurrency, progress, and graceful shutdown.

Recurring schedules

Stable schedule IDs, cron patterns, and migration.

Exact API reference

Every public producer, worker, payload, and durable type.