Scheduler

Scheduler

Simple time-based execution with minimal setup

Overview

The Astreus scheduler provides simple time-based execution for tasks and graphs using intuitive schedule strings. No complex configuration needed - just add a schedule field and you're done!

Basic Task Scheduling

Schedule individual tasks with simple syntax:

import { Agent } from '@astreus-ai/astreus';

const agent = await Agent.create({
  name: 'SchedulerAgent',
  model: 'gpt-4o'
});

// Create a scheduled task - scheduler starts automatically when needed
const scheduledTask = await agent.createTask({
  prompt: 'Generate monthly report for December',
  schedule: 'once@2024-12-25@09:00'
});

// Create a recurring task
const dailyTask = await agent.createTask({
  prompt: 'Daily health check and status report',
  schedule: 'daily@08:00'
});

// Execute the task - scheduler will handle the scheduling automatically
await agent.executeTask(scheduledTask.id);

Schedule Configuration

Use simple schedule strings for easy configuration:

// Supported schedule formats:
'daily@07:00'                    // Daily at 7 AM
'weekly@monday@09:00'            // Weekly on Monday at 9 AM  
'monthly@1@10:00'                // Monthly on 1st day at 10 AM
'hourly'                         // Every hour (default time)
'@15:30'                         // Once today at 3:30 PM
'once@2024-12-25@10:00'          // Once on specific date and time

// Examples:
await agent.createTask({
  prompt: 'Morning briefing',
  schedule: 'daily@08:00'
});

await agent.createTask({
  prompt: 'Weekly report',
  schedule: 'weekly@friday@17:00'
});

Graph Scheduling with Dependencies

Schedule graphs with intelligent dependency resolution:

import { Graph } from '@astreus-ai/astreus';

const graph = new Graph({
  name: 'Morning Workflow',
  defaultAgentId: agent.id
}, agent);

// Node A: Data collection at 6 AM
const nodeA = graph.addTaskNode({
  name: 'Data Collection',
  prompt: 'Collect overnight data from all sources',
  schedule: 'once@2024-12-20@06:00'
});

// Node B: Processing (depends on A completing first)
const nodeB = graph.addTaskNode({
  name: 'Data Processing',
  prompt: 'Process collected data and generate insights',
  schedule: 'once@2024-12-20@07:00',
  dependsOn: ['Data Collection'] // Must wait for A
});

// Node C: Report generation at 8 AM
const nodeC = graph.addTaskNode({
  name: 'Report Generation',
  prompt: 'Generate morning executive report',
  schedule: 'once@2024-12-20@08:00',
  dependsOn: ['Data Processing']
});

// Execute - scheduler starts automatically for scheduled nodes
await graph.run();

// Result: A runs at 06:00, B waits and runs after A (~06:05), C runs at 08:00

Recurring Patterns

Create sophisticated recurring schedules:

Daily Schedules

// Every day at 8 AM
{
  type: 'recurring',
  executeAt: new Date('2024-12-20T08:00:00Z'),
  recurrence: {
    pattern: 'daily',
    interval: 1,
    maxExecutions: 365 // Stop after 1 year
  }
}

// Every 3 days
{
  type: 'recurring',
  executeAt: new Date('2024-12-20T08:00:00Z'),
  recurrence: {
    pattern: 'daily',
    interval: 3
  }
}

Weekly Schedules

// Every Monday at 9 AM
{
  type: 'recurring',
  executeAt: new Date('2024-12-23T09:00:00Z'), // Monday
  recurrence: {
    pattern: 'weekly',
    interval: 1,
    daysOfWeek: [1] // Monday
  }
}

// Every Monday and Friday
{
  type: 'recurring',
  executeAt: new Date('2024-12-23T09:00:00Z'),
  recurrence: {
    pattern: 'weekly',
    interval: 1,
    daysOfWeek: [1, 5] // Monday and Friday
  }
}

Monthly and Yearly

// 15th of every month
{
  type: 'recurring',
  executeAt: new Date('2024-12-15T10:00:00Z'),
  recurrence: {
    pattern: 'monthly',
    interval: 1,
    dayOfMonth: 15
  }
}

// Every January 1st
{
  type: 'recurring',
  executeAt: new Date('2025-01-01T00:00:00Z'),
  recurrence: {
    pattern: 'yearly',
    interval: 1,
    monthOfYear: 1
  }
}

Scheduler Management

Monitor and control scheduled executions:

// Get scheduler status
const status = agent.getSchedulerStatus();
console.log(`Running: ${status.running}, Active jobs: ${status.activeJobs}`);

// List all scheduled items
const pending = await agent.listScheduledItems('pending');
const completed = await agent.listScheduledItems('completed');

// Get specific scheduled item
const item = await agent.getScheduledItem('task_123_456');

// Cancel a scheduled item
await agent.cancelScheduledItem('task_123_456');

// Delete a scheduled item
await agent.deleteScheduledItem('task_123_456');

// Stop the scheduler
await agent.stopScheduler();

Advanced Options

Configure retry logic and execution parameters:

await agent.scheduleTask({
  prompt: 'Critical system backup',
  schedule: {
    type: 'recurring',
    executeAt: new Date('2024-12-20T02:00:00Z'),
    recurrence: { pattern: 'daily', interval: 1 }
  },
  options: {
    maxRetries: 3,              // Retry failed executions
    retryDelay: 60000,          // 1 minute between retries
    timeout: 300000,            // 5 minute execution timeout
    respectDependencies: true   // Honor dependencies (default)
  }
});

Dependency Resolution Logic

The scheduler intelligently resolves conflicts between schedules and dependencies:

Scenario	Behavior
Node scheduled before dependency	Waits for dependency to complete
Node scheduled after dependency	Runs at scheduled time
Multiple dependencies	Waits for ALL dependencies
Circular dependencies	Error thrown during validation
Mixed scheduled/immediate nodes	Works seamlessly together

The scheduler provides a robust foundation for building automated, time-based AI workflows that respect dependencies and scale with your needs.

How is this guide?

On this page