# Scheduler
URL: /docs/framework/scheduler
Source: /app/src/content/docs/framework/scheduler.mdx

import { DocImage } from '@/components/DocImage';

<DocImage title="Scheduler" />

**Simple time-based execution with minimal setup**

import { Step, Steps } from 'fumadocs-ui/components/steps';

## 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:

```typescript
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:

```typescript
// 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:

```typescript
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:

<Steps>
  <Step>
    ### Daily Schedules

    ```typescript
    // 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
      }
    }
    ```
  </Step>

  <Step>
    ### Weekly Schedules

    ```typescript
    // 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
      }
    }
    ```
  </Step>

  <Step>
    ### Monthly and Yearly

    ```typescript
    // 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
      }
    }
    ```
  </Step>
</Steps>

## Scheduler Management

Monitor and control scheduled executions:

```typescript
// 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:

```typescript
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.