@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
Use a real model
Replace the deterministic provider with a provider from the model catalog. For example, installopenai, 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 ownsAgentQueue 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.