Schedules

Schedules enable agents to run automatically at specified times. Whether it's a daily report, hourly sync, or weekly cleanup, schedules handle the timing.

Why Schedules?

Automate recurring work without manual intervention:

• Daily reports: Generate summaries every morning
• Data sync: Keep systems in sync hourly
• Maintenance: Weekly cleanup and optimization
• Monitoring: Check system health every 5 minutes

Creating Schedules

Using Presets

// Every hour
const schedule = await client.schedules.create({
  name: 'Hourly Sync',
  agentId: 'agent-123',
  frequency: 'hourly',
  input: { syncType: 'incremental' }
});

// Every day at midnight
const schedule = await client.schedules.create({
  name: 'Daily Report',
  agentId: 'agent-123',
  frequency: 'daily',
  timezone: 'America/New_York',
  input: { reportType: 'daily-summary' }
});

// Every Monday at 9 AM
const schedule = await client.schedules.create({
  name: 'Weekly Review',
  agentId: 'agent-123',
  frequency: 'weekly',
  dayOfWeek: 1, // Monday
  hour: 9,
  timezone: 'America/New_York',
  input: { reviewType: 'team-metrics' }
});

Using Cron Expressions

For complex schedules, use cron syntax:

// Every 15 minutes
const schedule = await client.schedules.create({
  name: 'Frequent Check',
  agentId: 'agent-123',
  frequency: 'cron',
  cron: '*/15 * * * *',
  input: { checkType: 'health' }
});

// Weekdays at 9 AM and 5 PM
const schedule = await client.schedules.create({
  name: 'Business Hours Report',
  agentId: 'agent-123',
  frequency: 'cron',
  cron: '0 9,17 * * 1-5',
  timezone: 'America/New_York',
  input: { reportType: 'status' }
});

// First day of every month at midnight
const schedule = await client.schedules.create({
  name: 'Monthly Billing',
  agentId: 'agent-123',
  frequency: 'cron',
  cron: '0 0 1 * *',
  input: { action: 'generate-invoices' }
});

Cron Expression Reference

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Pattern	Description
* * * * *	Every minute
0 * * * *	Every hour
0 0 * * *	Every day at midnight
0 9 * * 1-5	Weekdays at 9 AM
*/15 * * * *	Every 15 minutes
0 0 1 * *	First of every month
0 0 * * 0	Every Sunday

Validate Cron Expression

const validation = await client.schedules.validateCron('0 9 * * 1-5');

console.log(validation.valid);       // true
console.log(validation.description); // "At 09:00 on Monday through Friday"
console.log(validation.nextRuns);    // Next 5 execution times

Frequency Options

Frequency	Description	Additional Config
once	Run once at specific time	runAt
hourly	Every hour	minute
daily	Every day	hour, minute
weekly	Every week	dayOfWeek, hour, minute
monthly	Every month	dayOfMonth, hour, minute
cron	Custom cron expression	cron

One-Time Schedule

const schedule = await client.schedules.create({
  name: 'One-Time Migration',
  agentId: 'agent-123',
  frequency: 'once',
  runAt: '2024-12-31T23:59:00Z',
  input: { action: 'migrate-data' }
});

Schedule Configuration

With Retry Settings

const schedule = await client.schedules.create({
  name: 'Reliable Sync',
  agentId: 'agent-123',
  frequency: 'hourly',
  maxRetries: 3,       // Retry up to 3 times on failure
  timeoutMs: 120000,   // 2 minute timeout per run
  input: { syncType: 'full' }
});

With Date Bounds

const schedule = await client.schedules.create({
  name: 'Q4 Campaign',
  agentId: 'agent-123',
  frequency: 'daily',
  hour: 9,
  startDate: '2024-10-01',
  endDate: '2024-12-31',
  input: { campaign: 'q4-2024' }
});

With Memory Persistence

const schedule = await client.schedules.create({
  name: 'Incremental Processor',
  agentId: 'agent-123',
  frequency: 'hourly',
  enableMemory: true, // Agent remembers state between runs
  input: { mode: 'incremental' }
});

Managing Schedules

Pause Schedule

await client.schedules.pause('schedule-123');

Resume Schedule

await client.schedules.resume('schedule-123');

Run Immediately

Trigger a schedule run outside its normal timing:

const run = await client.schedules.run('schedule-123');

Update Schedule

await client.schedules.update('schedule-123', {
  frequency: 'daily',
  hour: 10, // Changed from 9 AM to 10 AM
  input: { updatedParam: true }
});

Delete Schedule

await client.schedules.delete('schedule-123');

Monitoring Schedules

Get Schedule Details

const schedule = await client.schedules.get('schedule-123');

console.log({
  status: schedule.status,
  lastRunAt: schedule.lastRunAt,
  nextRunAt: schedule.nextRunAt,
  runCount: schedule.runCount,
  failureCount: schedule.failureCount
});

Preview Next Runs

const schedule = await client.schedules.get('schedule-123');

// Shows next 5 scheduled execution times
console.log(schedule.nextRuns);
// [
//   "2024-01-15T09:00:00Z",
//   "2024-01-16T09:00:00Z",
//   "2024-01-17T09:00:00Z",
//   "2024-01-18T09:00:00Z",
//   "2024-01-19T09:00:00Z"
// ]

List Schedule Runs

const runs = await client.schedules.listRuns('schedule-123', {
  limit: 20,
  status: 'failed' // Filter to see failures
});

for (const run of runs.data) {
  console.log({
    startedAt: run.startedAt,
    status: run.status,
    error: run.error
  });
}

Schedule Presets

Get common schedule patterns:

const presets = await client.schedules.getPresets();

// Returns:
// [
//   { name: "Every minute", cron: "* * * * *" },
//   { name: "Every 5 minutes", cron: "*/5 * * * *" },
//   { name: "Every 15 minutes", cron: "*/15 * * * *" },
//   { name: "Every hour", cron: "0 * * * *" },
//   { name: "Every day at midnight", cron: "0 0 * * *" },
//   { name: "Every day at 9 AM", cron: "0 9 * * *" },
//   { name: "Every Monday at 9 AM", cron: "0 9 * * 1" },
//   { name: "First of every month", cron: "0 0 1 * *" }
// ]

Dashboard Configuration

From the Dashboard:

1. Go to Agents → Select agent → Schedules
2. Click + Create Schedule
3. Choose frequency (preset or custom cron)
4. Set timezone
5. Configure retry and timeout settings
6. Add input parameters
7. Click Create

Best Practices

1. Use Appropriate Timezones

// ✅ Good - explicit timezone
timezone: 'America/New_York'

// ❌ Bad - assumes UTC
// (no timezone specified)

2. Stagger Heavy Schedules

Don't run all heavy tasks at the same time:

// Reports at different times to spread load
{ name: 'Sales Report', cron: '0 6 * * *' }  // 6 AM
{ name: 'Marketing Report', cron: '0 7 * * *' }  // 7 AM
{ name: 'Finance Report', cron: '0 8 * * *' }  // 8 AM

3. Configure Retries for Network Operations

// External API calls may fail transiently
maxRetries: 3

4. Set Reasonable Timeouts

// Match timeout to expected duration
timeoutMs: 60000 // 1 minute for quick tasks
timeoutMs: 300000 // 5 minutes for longer tasks

5. Use Memory for Incremental Processing

// Agent can track what was already processed
enableMemory: true,
input: { mode: 'incremental' }

Example: Daily Report Schedule

const schedule = await client.schedules.create({
  name: 'Daily Sales Report',
  description: 'Generate and email daily sales summary',
  agentId: 'report-agent',
  frequency: 'daily',
  hour: 7,
  minute: 0,
  timezone: 'America/New_York',
  maxRetries: 2,
  timeoutMs: 180000, // 3 minutes
  input: {
    reportType: 'sales-summary',
    period: 'yesterday',
    recipients: ['sales-team@company.com'],
    format: 'pdf'
  }
});

---

Next: Learn about Triggers for webhook-based agent execution.