Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xhipai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Queue Overview

Agentium provides a queue system for running agents and workflows as background jobs. Use it when you need to process long-running tasks asynchronously, scale workers independently, or retry failed runs.

​
Architecture

AgentQueue

Producer. Enqueue agent runs and workflows. Returns job IDs for status tracking.

AgentWorker

Consumer. Processes jobs from the queue using your agent and workflow registries.
Both use BullMQ backed by Redis. You need a running Redis server.

​
Dependencies

npm install @agentium/queue bullmq ioredis
Redis must be running. BullMQ uses it for job storage, scheduling, and coordination. 
# Local Redis (macOS)
brew services start redis

# Or Docker
docker run -d -p 6379:6379 redis:alpine

​
Quick Start

import { AgentQueue, AgentWorker } from "@agentium/queue";
import { Agent, openai } from "@agentium/core";

const agent = new Agent({
  name: "Worker",
  model: openai("gpt-4o"),
  instructions: "You are helpful.",
});

const queue = new AgentQueue({
  connection: { host: "localhost", port: 6379 },
});

const worker = new AgentWorker({
  connection: { host: "localhost", port: 6379 },
  agentRegistry: { worker: agent },
});

// Enqueue a job
const { jobId } = await queue.enqueueAgentRun({
  agentName: "worker",
  input: "Hello!",
});

// Check status
const status = await queue.getJobStatus(jobId);
console.log(status.state); // "waiting" | "active" | "completed" | "failed"

​
Job Types

TypeEnqueue MethodPayload
AgentenqueueAgentRun()agentName, input, sessionId?, userId?
WorkflowenqueueWorkflow()workflowName, initialState?, sessionId?

​
Job Lifecycle

1

Enqueue

Producer adds a job to the Redis-backed queue. Returns jobId.
2

Wait

Job sits in the queue until a worker picks it up.
3

Process

Worker runs the agent or workflow. Progress can be reported via job.updateProgress().
4

Complete or Fail

Result is stored (or error recorded). onCompleted / onFailed handlers fire.

​
Scaling

  • Run multiple workers on different processes or machines. BullMQ distributes jobs across them.
  • Use concurrency per worker to process several jobs in parallel.
  • Use priority and delay for scheduling.

​
Next Steps

  • Producer — AgentQueue, enqueue methods, job status
  • Worker — AgentWorker, concurrency, event bridging