A cron is a scheduled trigger that fires an agent loop at a specified time or interval.
Cron is the operator's way of making the agent do work on a schedule. Cron is to the agent what a calendar reminder is to a human: a regular, reliable nudge that the agent should pick up the specified task. Cron is also the mechanism by which the agent's long-running work is broken into daily, hourly, or per-minute units.
The cron spec
A cron spec is a five-field expression that defines the schedule:
minute hour day-of-month month day-of-week
* * * * *The fields are interpreted in the operator's local timezone. The spec is parsed by the cron runtime, and the cron runtime fires the agent loop at the specified times. The cron spec is the operator's contract with the runtime.
Why cron is the right abstraction
Cron is the right abstraction for scheduled work because cron is deterministic, cron is observable, and cron is recoverable. The cron spec is parsed by the runtime, the runtime knows when the next fire is, and the runtime can recover the next fire after a restart. The agent loop is then triggered by the cron, and the agent loop can focus on the work without worrying about the schedule.
The cron failure modes
The most common operator issues with cron are: the cron is firing at the wrong time (the timezone is set incorrectly), the cron is firing too often (the rate is too high), the cron is not firing (the spec is malformed), the cron is firing but the agent is failing (the agent loop is broken), and the cron is doubling up (a previous run is still going when the next run fires). The cron is the right place to start when an operator is debugging an agent that is not producing the expected output at the expected time.
Cron vs. heartbeat
Cron is the right abstraction for scheduled work (do this thing at this time). Cron is the wrong abstraction for reactive work (do this thing when something happens). For reactive work, use a webhook or a queue. For continuous work that needs to be triggered by time, use cron. For work that needs to be checked regularly, use a heartbeat — see the cron vs heartbeat glossary entry for the comparison.
Related terms
A cron is the trigger for an agent loop's first step. The cron fires a session that runs the loop. The cron's output is the memory that the next session reads. The cron's reliability is one of the inputs to the observability layer. The cron's rate is one of the inputs to the algorithm that decides when the agent should back off.
For the full primer, see Cron, Skills, Loops, Lobsters, and Workboard.
Cron's role in the agent's lifecycle
Cron is the trigger for the agent's recurring work. The cron's schedule is the agent's heartbeat; the cron's output is the agent's daily record. The cron is the right abstraction for the recurring work because the cron is precise, the cron is observable, and the cron is recoverable.
The cron's reliability is the operator's first concern. The cron that fires late is the cron that misses its window. The cron that fires twice is the cron that produces duplicate work. The cron that does not fire is the cron that silently breaks the agent's schedule. The cron is the right place to start when an operator is debugging an agent that is not producing the expected output at the expected time.