Schedule recurring or one-time AI agent tasks with cron expressions and delayed execution — automate daily reports, polling, and time-driven workflows across the swarm.

Agent Swarm supports both recurring and one-time schedules to automate work. A schedule can create an agent task (targetType: "agent-task"), trigger a workflow directly, or run a saved catalog script without an agent session in the loop.

Creating a Recurring Schedule

create-schedule(
  name: "daily-standup",
  taskTemplate: "Generate a daily standup report summarizing yesterday's completed tasks",
  cronExpression: "0 9 * * *",
  timezone: "America/New_York",
  targetType: "agent-task"
)

Or use interval-based scheduling:

create-schedule(
  name: "health-check",
  scriptName: "service-health-check",
  scriptArgs: { channel: "ops" },
  targetType: "script",
  intervalMs: 3600000
)

Creating a One-Time Schedule

One-time schedules run once and then auto-disable. Use delayMs for a relative delay or runAt for an absolute time:

create-schedule(
  name: "deploy-reminder",
  scheduleType: "one_time",
  taskTemplate: "Remind the team about the deployment at 3 PM",
  delayMs: 1800000
)

create-schedule(
  name: "scheduled-report",
  scheduleType: "one_time",
  taskTemplate: "Generate the quarterly report",
  runAt: "2026-03-15T09:00:00Z"
)

Schedule Properties

Property	Description
`name`	Unique name for the schedule
`targetType`	`agent-task` (default), `workflow`, or `script`
`taskTemplate`	Task description created each time. Required for `agent-task` schedules
`workflowId`	Workflow to trigger when `targetType: "workflow"`
`scriptName`	Global catalog script name to run when `targetType: "script"`
`scriptArgs`	JSON arguments passed to the script target
`scheduleType`	`recurring` (default) or `one_time`
`cronExpression`	Cron expression for recurring schedules (e.g., `0 9 * * *`)
`intervalMs`	Interval in milliseconds for recurring schedules
`delayMs`	Delay in milliseconds for one-time schedules
`runAt`	ISO datetime for one-time schedules (e.g., `2026-03-15T09:00:00Z`)
`timezone`	Timezone for cron schedules (default: UTC)
`targetAgentId`	Agent to assign tasks to (omit for task pool)
`priority`	Task priority 0-100 (default: 50)
`tags`	Tags applied to created tasks
`taskType`	Type classification for created tasks
`model`	Concrete model override for created agent tasks
`modelTier`	Portable model intent for created agent tasks: `smol`, `regular`, `smart`, or `ultra`
`enabled`	Whether the schedule is active (default: true)

Choosing `targetType`

Pick the schedule target that matches the work you actually want to fire:

Use agent-task when a reasoning agent needs to read the prompt, use tools, and make judgment calls before doing the work.
Use workflow when the schedule's only job is to start an existing workflow DAG. Pass workflowId and skip agent-task fields that only apply to delegated tasks.
Use script when the schedule should run a saved catalog script directly with scriptName and optional scriptArgs, without opening an interactive agent session.

This avoids a common anti-pattern: creating an agent-task schedule whose task body only says "trigger workflow X" or "run script Y". If the work is already captured as a workflow or script, schedule that target directly.

Managing Schedules

List Schedules

list-schedules()
list-schedules(enabled: true)
list-schedules(name: "daily")
list-schedules(scheduleType: "one_time")

By default, completed one-time schedules are hidden. Pass hideCompleted: false to include them.

Update a Schedule

update-schedule(name: "daily-standup", cronExpression: "0 10 * * *")
update-schedule(name: "daily-standup", enabled: false)
update-schedule(name: "health-check", targetType: "workflow", workflowId: "<workflow-uuid>")

Delete a Schedule

delete-schedule(name: "daily-standup")

Run Immediately

Trigger a scheduled task now without waiting for the next interval:

run-schedule-now(name: "daily-standup")

This creates a task immediately but does not affect the regular schedule timing.

Cron Expression Examples

Expression	Description
`0 9 * * *`	Every day at 9:00 AM
`0 9 * * 1-5`	Weekdays at 9:00 AM
`/30 * * *`	Every 30 minutes
`0 0 * * 0`	Every Sunday at midnight
`0 9,17 * * *`	At 9 AM and 5 PM daily

How Scheduling Works

The MCP server runs a scheduler that polls for due schedules at a configurable interval (default: 10 seconds, set via SCHEDULER_INTERVAL_MS).

When a schedule fires, execution depends on targetType:

agent-task — creates a task from taskTemplate (the original behavior)
workflow — runs the referenced workflow directly and returns workflowRunIds
script — launches the named global script directly and returns scriptRunIds

For agent-task schedules:

A new task is created with the schedule's taskTemplate
The task is linked back to its schedule via scheduleId
If targetAgentId is set, the task is assigned to that agent; otherwise it goes into the unassigned pool
If model or modelTier is set, the task inherits that runtime selection
The schedule's lastRunAt is updated
One-time schedules are automatically disabled after execution

Direct Workflow and Script Targets

Native targetType replaces the old "workflow trigger references a schedule" indirection for many cases:

{
  "name": "nightly-pipeline",
  "targetType": "workflow",
  "workflowId": "<workflow-uuid>"
}

Use targetType: "script" plus scriptName / scriptArgs when the scheduled work is a reusable script and does not need an interactive agent task.

Any registered agent can update or delete schedules.

Task Lifecycle — How scheduled tasks flow through the system after creation
Environment Variables — SCHEDULER_INTERVAL_MS and other configuration
MCP Tools Reference — Scheduling tools (create-schedule, list-schedules, etc.)
Schedules API Reference — REST API endpoints for creating and managing schedules

Scheduled Tasks