Heartbeat

A heartbeat is the trigger that wakes the Sprout agent to do something on a cadence. Cron-driven today, event-driven soon. Each fire runs a skill: refreshing today's task, posting a daily brief, scheduling tomorrow's work. The heartbeat is the rhythm; the skill is the work.

Heartbeats are powerful, and the two-skill pattern (run skill + assignment skill) earns its keep. They're also rarely the right first reach: a recurring task with scheduleSpec already handles fixed-content recurrence with zero machinery.

Where you'll see this

In the wild: Schedule a heartbeat (Build) · Save it as a skill (the morning-refresh example)

A worked example

The morning refresh from the Skill page, on a heartbeat. 8am weekdays, runs the refresh skill.

heartbeat.create({
name: "Morning check-in refresh",
cron: "0 8 * * 1-5",
tz: "America/New_York",
runSkillId: "<refresh-skill>",
skillInput: {
child_name: "Jay",
child_id: "<childId>",
today: "{{fireDate}}"
},
postResultNotify: true
})
# heartbeat.describe(...) previews the cadence + first fire before commit.

For the two-skill pattern (a separate assignmentSkillId that owns the schedule for audit), pass both. With #1107, assignmentSkillId is optional: pass it when you want the scheduler itself to be an auditable skill.

Shape

• name: human-readable label.
• cron · tz: 5-field cron in the heartbeat's timezone. Defaults to America/New_York.
• runSkillId: required. The skill the heartbeat runs each fire. Must be run-shaped (no heartbeat.create in its hands).
• assignmentSkillId: optional. The skill that owns the schedule, for audit and library purposes.
• childId: optional. Scope to one kid; omit for family-wide.
• skillInput: structured values filling the skill's {{input.*}} placeholders. Same map every fire.
• postResultNotify: whether the structured result posts to the family inbox.

When to use it (and when not to)

Try a recurring task first. If the kid sees the same prompt every weekday, task.create with taskType: "schedule" + days already handles that. Zero heartbeats needed.

Use a heartbeat when:

• Each fire should produce fresh content (today's plan, this evening's reflection, a new homework drill).
• The cadence is anything cron can express but a weekday list can't (every other day, monthly, 7:30am weekdays only).
• The output goes to the family inbox as a recurring brief, not a kid task.

Common errors

• BAD_INPUT · cadence cap , cron computes to more than 4 fires per 24h. Slow it down or use a different surface.
• BAD_INPUT · SCHEDULER_AS_RUN_SKILL , runSkillId declares heartbeat.create. Run skill is delivery, not scheduling.
• BAD_INPUT · SKILL_NOT_ASSIGNMENT , assignmentSkillId doesn't declare heartbeat.create.
• PERMISSION_DENIED: invoking on a home_agent skill. Server refuses.

Related tools

• heartbeat.create: author. Idempotency-keyed.
• heartbeat.update: discrete actions: edit_schedule, edit_name, pause, resume, cancel, members.
• heartbeat.describe: preview the cadence and first-fire timestamp before committing.
• heartbeat.list: find the id.

Roadmap for this noun

• Soon Event-driven triggers: fire on activity events (task completed, gem earned, screen-time requested), not just on a clock.
• Soon Longer-cadence cap relaxation: case-by-case, for parent-facing briefs that don't need the 4/24 protection.

Related reading

Schedule a heartbeat Skill Activity