Skip to main content
Schedule lets you create timed executions for your agents — from code or from the agent itself during a conversation. When a user says “remind me tomorrow at 9am”, the agent can create that schedule automatically.

​
Quick Start: Agent with Schedule

Give your agent the ability to create, list, update, and cancel schedules: 
import { Agent, openai, createScheduleTools } from '@runflow-ai/sdk';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant. You can schedule reminders and recurring tasks.',
  model: openai('gpt-4o'),
  tools: {
    ...createScheduleTools(),
  },
});
Now the agent handles conversations like:
User: “Me chama amanha as 9h pra eu enviar o relatorio” Agent: uses create_schedule tool — Schedule “Lembrete relatorio” created. I’ll remind you tomorrow at 09:00.
User: “Quais lembretes eu tenho?” Agent: uses list_schedules tool — You have 2 active schedules: …
User: “Cancela o lembrete do relatorio” Agent: uses cancel_schedule tool — Schedule cancelled.

​
Agent Tools

createScheduleTools() returns 4 tools that the LLM can invoke:
ToolDescription
create_scheduleCreate a new scheduled execution
list_schedulesList all active schedules for this agent
update_scheduleUpdate an existing schedule
cancel_scheduleCancel (delete) a schedule

​
Programmatic API

Use the schedule object directly in your code:

​
Create a Schedule

import { schedule } from '@runflow-ai/sdk';

// Daily at 9am
await schedule.create({
  name: 'Daily Report',
  type: 'daily',
  time: '09:00',
  timezone: 'America/Sao_Paulo',
  message: 'Generate the daily sales report',
});

// Every 2 hours
await schedule.create({
  name: 'Check Tickets',
  type: 'interval',
  interval: 120,  // minutes
  message: 'Check for new support tickets and summarize',
});

// Cron expression
await schedule.create({
  name: 'Weekly Summary',
  type: 'cron',
  cron: '0 9 * * MON',
  timezone: 'America/Sao_Paulo',
  message: 'Generate the weekly performance summary',
});

// One-time reminder
await schedule.create({
  name: 'Send proposal',
  type: 'daily',
  time: '14:00',
  timezone: 'America/Sao_Paulo',
  message: 'Remind the user to send the proposal to client X',
  maxExecutions: 1,  // Runs once, then stops
});

​
List Schedules

const schedules = await schedule.list();

for (const s of schedules) {
  console.log(`${s.name} - ${s.type} - ${s.status}`);
}

​
Update a Schedule

await schedule.update('schedule-id', {
  time: '10:00',  // Change from 9am to 10am
});

​
Cancel a Schedule

await schedule.cancel('schedule-id');

​
Schedule Types

​
Interval

Runs every N minutes: 
{
  type: 'interval',
  interval: 60,  // Every hour (1-43200 minutes)
}

​
Daily

Runs at a specific time every day: 
{
  type: 'daily',
  time: '09:00',       // HH:mm format
  timezone: 'America/Sao_Paulo',
}

​
Cron

Full cron expression support: 
{
  type: 'cron',
  cron: '0 9 * * MON-FRI',  // Weekdays at 9am
  timezone: 'America/Sao_Paulo',
}
Common cron patterns:
ExpressionDescription
0 9 * * *Every day at 9am
0 9 * * MON-FRIWeekdays at 9am
0 9 * * MONEvery Monday at 9am
0 */2 * * *Every 2 hours
0 9,18 * * *At 9am and 6pm

​
Configuration Options

ParameterTypeRequiredDefaultDescription
namestringYes—Schedule name
type'interval' | 'daily' | 'cron'Yes—Schedule type
intervalnumberWhen type is interval—Minutes between executions (1-43200)
timestringWhen type is daily—Time in HH:mm format
cronstringWhen type is cron—Cron expression
timezonestringNoAmerica/Sao_PauloTimezone
messagestringYes—Message sent to the agent on each execution
maxExecutionsnumberNo0 (unlimited)Max number of executions. Use 1 for one-time reminders
metadataobjectNo—Custom metadata

​
Using in Workflows

import { flow, schedule } from '@runflow-ai/sdk';

const onboardingFlow = flow('customer-onboarding')
  .step('welcome', {
    agent: welcomeAgent,
    prompt: ({ input }) => `Welcome the new customer: ${input.customerName}`,
  })
  .step('schedule-followup', async ({ input, results }) => {
    await schedule.create({
      name: `Follow-up: ${input.customerName}`,
      type: 'daily',
      time: '10:00',
      timezone: 'America/Sao_Paulo',
      message: `Check in with ${input.customerName} about their onboarding progress`,
      maxExecutions: 5,  // Follow up for 5 days
    });
    return { scheduled: true };
  })
  .build();

​
How It Works

Schedules are powered by the Runflow trigger engine:
  1. SDK calls POST /runtime/v1/schedules on the Runflow API
  2. API creates a SCHEDULER type trigger in the trigger engine
  3. Trigger engine uses Redis key expiration events to fire at the right time
  4. On each execution, the trigger engine sends the message to the agent
  5. Agent processes the message and generates a response
Schedules are isolated per agent — each agent can only see and manage its own schedules.

​
Next Steps

Web Search

Give agents internet search capabilities

Connectors

Connect to external APIs