Cron fires at scheduled times; heartbeats poll regularly and decide what to do.
Cron is precision: the agent is asked to do a specific thing at a specific time. Heartbeats are awareness: the agent is asked to check in regularly and decide what to do based on what it sees. The two patterns are complementary, and most long-running systems use both.
When to use cron
Use cron when the work is scheduled. The work has a specific time or interval, and the agent should do the work at that time. Examples of cron work: a daily report, a weekly recap, an hourly check, a per-minute data sync.
Cron is the right pattern for work that is:
- Predictable. The agent knows when the work is needed.
- Cheap. The cost of the work is bounded.
- Idempotent. Running the work twice is the same as running it once.
- Time-sensitive. The work is more valuable at the scheduled time.
When to use heartbeat
Use heartbeat when the work is reactive. The agent checks in regularly, and the agent decides what to do based on what it sees. Examples of heartbeat work: a daily metrics check, a weekly task review, a periodic cleanup, a summary of recent events.
Heartbeat is the right pattern for work that is:
- Variable. The agent does not know when the work is needed.
- Adaptive. The agent's response depends on the state.
- Bounded. The agent does a bounded amount of work per check.
- Cheap. The cost of the check is low.
Why both
Most long-running systems use both cron and heartbeats. The cron fires the time-sensitive work (the daily report, the hourly check), and the heartbeats do the reactive work (the daily metrics check, the weekly task review). The two patterns are complementary: the cron is the right pattern for the work that is scheduled, and the heartbeat is the right pattern for the work that is reactive.
The cost of the two patterns is different. The cron is cheap to fire (the cron runtime knows when the next fire is, and the cron runtime fires the agent loop only at the specified times). The heartbeat is more expensive to fire (the heartbeat runtime fires the agent loop every N minutes, and the agent loop decides whether to do work). The right balance is to use cron for the work that is scheduled and to use heartbeat for the work that is reactive.
Operator implications
The cron vs. heartbeat decision is the right place to start when an operator is adding a new recurring task to an agent system. The most common operator issue with cron and heartbeats is that the operator uses the wrong pattern: the operator uses cron for reactive work (the cron is firing at a time when the work is not needed), or the operator uses heartbeat for scheduled work (the heartbeat is firing too often and costing too much). The pattern is the right place to start when an operator is debugging an agent that is not producing the expected output.
Related terms
Cron is the trigger for an agent loop's scheduled step. Heartbeat is the trigger for the loop's reactive step. The cron's output is one of the inputs to the memory layer. The heartbeat's output is one of the inputs to the observability layer. The cron's reliability is one of the operator's HITL checks.
For the full comparison, see Cron vs Heartbeat.