Scheduler

Learn about Scheduler in the Astreus documentation, with setup guidance, API patterns, and practical examples for building agent systems.

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

// Delay-based schedules:
'after:5s'                       // Run after 5 seconds
'after:30m'                      // Run after 30 minutes
'after:2h'                       // Run after 2 hours

// 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
  }
}

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.

Last updated: May 26, 2026

Graph

Knowledge