Heartbeat
The Agent Framework introduces the heartbeat as a recurring trigger that gives the agent ambient awareness — the freedom to notice things and act only when something warrants it. The design question is: what makes a good heartbeat, and why is it harder than it looks?
What a heartbeat is
Section titled “What a heartbeat is”A heartbeat is a periodic prompt at a set interval. Every interval, the agent wakes up, looks at the world, and decides whether anything needs its attention.
There is no technical reason an agent could not have multiple heartbeats, but for the sake of keeping the concept simple we treat an agent as having a single heartbeat. If you find yourself wanting more than one, that is usually a sign you want schedules instead.
Mechanically, a heartbeat is just a schedule running at a constant interval — a cron that fires every N minutes. The difference is not what happens under the hood; it is conceptual. A schedule is tied to a specific time and a specific task. A heartbeat is untied from any particular moment, and the agent decides each time whether to act.
The heartbeat itself is simple — just a tick. The intelligence comes from the layers beneath it. Sharp instructions tell the agent what to notice. Good skills tell it how to act. The heartbeat just gives it the opportunity.
Think of it as walking the floor. A schedule is a calendar event — be somewhere specific at a specific time to do a specific thing. A heartbeat is a manager walking the floor — checking in, looking around, and stepping in only when something needs it.
The distinction from schedules
Section titled “The distinction from schedules”This is the key design decision:
| Schedule | Heartbeat | |
|---|---|---|
| Purpose | Execute a specific task | Stay aware, act on judgment |
| Output | Expected deliverable | Only if warranted |
| Multiplicity | Many per agent | One per agent (by convention) |
| Analogy | Calendar event | Walking the floor |
If you know exactly what the agent should produce at a given time, use a schedule. If the agent should watch for things and decide whether to act, use a heartbeat.
Why heartbeats are powerful — and hard
Section titled “Why heartbeats are powerful — and hard”When a heartbeat works well, the agent feels genuinely intelligent. It notices things, responds to changing situations, and takes initiative without being asked. It behaves like a thoughtful teammate who is always paying attention.
But designing heartbeats is one of the hardest parts of agent engineering. The heartbeat fires into a huge space of possible situations — different times of day, different states of the world, different things the user is working on — and the agent has to make a good decision in every one of them. The prompt interacts with the system prompt, the skills, the tools, and whatever the agent discovers in the moment. Predicting what the agent will do across all these combinations is genuinely difficult — and most beats should produce nothing at all.
The single most useful heuristic: the shorter and simpler the heartbeat prompt, the less there is that can be totally wrong. A long, clever heartbeat prompt multiplies the ways the agent can misfire. A short one gives it fewer chances to go astray.
A heartbeat that produces output every time is probably a schedule in disguise. A heartbeat that never produces anything useful is missing the intelligence it needs to act.
Design principles
Section titled “Design principles”Keep the prompt generic. The heartbeat prompt itself should be simple — often just “check for anything that needs your attention.” The intelligence lives in the instructions and skills, not in the heartbeat prompt.
Act only when warranted. Most beats should be quiet. Design for the exceptional case, not the routine one. If your heartbeat always takes action, you have built a scheduled task.
Prerequisites matter. A heartbeat without clear instructions is an agent checking in with nothing to check. Before adding a heartbeat, make sure the agent’s instructions define what it should care about. “Track the user’s north star priority” is the kind of standing duty that gives a heartbeat something to watch for.
Start conservative. A heartbeat that is too eager will feel like noise. A heartbeat that is too quiet can always be sharpened. Err toward quiet and expand as you see how the agent behaves.
The heartbeat and instructions
Section titled “The heartbeat and instructions”A heartbeat is only as good as the instructions behind it. The pattern to aim for:
- The instructions say what the agent should notice and care about.
- The heartbeat gives the agent regular opportunities to act on those concerns.
For a focus coach agent, the instructions might include “track the user’s north star priority and flag tasks that drift from it.” The heartbeat then prompts the agent every few hours to check in — and because the instructions already tell it what to watch for, the heartbeat does not need to repeat that logic.
This separation is what makes heartbeats tractable. The heartbeat prompt stays short and generic. The instructions evolve as you learn what the agent should pay attention to. Adding a new concern usually means updating the instructions, not the heartbeat.
The line between the two is genuinely fuzzy. The same behavior could often be achieved by putting the logic in the heartbeat prompt instead — or by leaning on the instructions and keeping the heartbeat as a bare tick. Both can work. The right choice depends on whether the behavior is something the agent should consider in every interaction (instructions) or only when the heartbeat fires (heartbeat prompt).
Start without one
Section titled “Start without one”A heartbeat is the single best way to make an agent feel extremely intelligent — and the single easiest way to make it feel stupid and annoying. An agent that chimes in with nothing useful, checks in for no reason, or misjudges when to act will quickly train you to ignore it — and at that point, it has negative value.
The right default is to build responsive agents first. Add a heartbeat only when you have a clear vision for what it should watch for and why. If you are adding a heartbeat just so the agent “does something on its own,” do not. The agent fooling around every few hours is worse than an agent that simply waits to be asked.
Ask: between conversations, is there something the agent should be paying attention to that you can describe clearly? If you cannot articulate it, the heartbeat is not ready to exist yet.