queue

Queue System

The Agents SDK provides a built-in queue system that allows you to schedule tasks for asynchronous execution. This is particularly useful for background processing, delayed operations, and managing workloads that don't need immediate execution.

Overview

The queue system is built into the base Agent class. Tasks are stored in a SQLite table and processed automatically in FIFO (First In, First Out) order.

QueueItem Type

export type QueueItem<T = string> = {
  id: string; // Unique identifier for the queued task
  payload: T; // Data to pass to the callback function
  callback: keyof Agent<unknown>; // Name of the method to call
  created_at: number; // Timestamp when the task was created
  retry?: RetryOptions; // Retry options (if configured)
};

Core Methods

queue()

Adds a task to the queue for future execution.

async queue<T = unknown>(
  callback: keyof this,
  payload: T,
  options?: { retry?: RetryOptions }
): Promise<string>

Parameters:

• callback: The name of the method to call when processing the task
• payload: Data to pass to the callback method
• options.retry: Optional retry configuration. See Retries for details.

Returns: The unique ID of the queued task

Example:

class MyAgent extends Agent {
  async processEmail(data: { email: string; subject: string }) {
    // Process the email
    console.log(`Processing email: ${data.subject}`);
  }

  async onMessage(message: string) {
    // Queue an email processing task
    const taskId = await this.queue("processEmail", {
      email: "[email protected]",
      subject: "Welcome!"
    });

    console.log(`Queued task with ID: ${taskId}`);
  }
}

dequeue()

Removes a specific task from the queue by ID.

dequeue(id: string): void

Parameters:

• id: The ID of the task to remove

Example:

// Remove a specific task
agent.dequeue("abc123def");