AI Agent Heartbeat

An AI agent heartbeat is a periodic polling mechanism that lets agents check for work on a schedule without constant human input. Like a biological heartbeat that keeps organisms alive, agent heartbeats keep AI systems responsive and aware—waking periodically to check their environment, process pending tasks, and take action when needed.

The pattern solves a fundamental challenge: how do you make an AI agent feel "alive" and proactive rather than purely reactive? Heartbeats provide the rhythm.

Every 30 minutes:
  → Agent wakes
  → Checks for new emails, calendar events, notifications
  → Processes any pending tasks
  → Takes proactive actions if needed
  → Returns to sleep (or replies HEARTBEAT_OK if nothing to do)

This simple pattern transforms AI from a tool you invoke into a collaborator that watches your back.

The basic loop

A heartbeat system periodically triggers the agent with a prompt like:

"Check if anything needs attention. If nothing requires action, reply HEARTBEAT_OK."

The agent then:

1. Reads its current context (recent messages, pending tasks, environment state)
2. Checks configured data sources (email, calendar, notifications)
3. Decides if action is needed
4. Either takes action or acknowledges with HEARTBEAT_OK

Heartbeat configuration

Typical heartbeat settings include:

• Interval: How often to poll (5 minutes to several hours)
• Prompt: What instructions the agent receives
• Quiet hours: When to suppress heartbeats (late night)
• Priority checks: What sources to monitor

State tracking

Smart heartbeat systems track what's been checked:

{
  "lastChecks": {
    "email": "2024-01-15T10:30:00Z",
    "calendar": "2024-01-15T10:00:00Z",
    "notifications": "2024-01-15T09:30:00Z"
  }
}

This prevents redundant checks and enables rotation through different data sources.

From reactive to proactive

Without heartbeats, agents only respond when explicitly invoked. With heartbeats, agents can:

• Notice an urgent email and alert you
• Remind you about an upcoming meeting
• Flag a calendar conflict before it's a problem
• Surface relevant news or updates

The agent becomes a proactive assistant, not just a responsive tool.

Continuous awareness

Heartbeats create the illusion of continuous attention with discrete, efficient checks. The agent isn't constantly running—it wakes, checks, acts if needed, and sleeps.

Background processing

Some tasks benefit from background execution:

• Periodic data syncs
• Regular report generation
• Ongoing monitoring
• Incremental memory organization

Heartbeats provide natural checkpoints for this work.

Basic implementation

import schedule
import time

def heartbeat():
    response = agent.invoke(
        "Check if anything needs attention. "
        "If nothing requires action, reply HEARTBEAT_OK."
    )
    
    if response != "HEARTBEAT_OK":
        # Agent took action or has something to report
        notify_user(response)

# Run every 30 minutes
schedule.every(30).minutes.do(heartbeat)

while True:
    schedule.run_pending()
    time.sleep(60)

Configurable heartbeat file

Production systems often use a configuration file (like HEARTBEAT.md) that the agent reads:

# Heartbeat Checklist

On each heartbeat, check:
- [ ] Unread emails (urgent only)
- [ ] Calendar events in next 2 hours
- [ ] Pending tasks in task list
- [ ] Any mentions or notifications

If nothing needs attention, reply HEARTBEAT_OK.
Don't repeat information from the last heartbeat.

This lets you modify agent behavior without code changes.

Smart scheduling

Not all checks need the same frequency:

• Email: Every 30 minutes
• Calendar: Every hour
• News/social: Every few hours
• Deep work review: Once daily

Rotate through checks to balance coverage with efficiency.

Batch related checks

One heartbeat can check multiple things:

→ Check email + calendar + notifications
→ Process all, respond once

This reduces overhead compared to separate heartbeats for each.

Respect quiet hours

Define periods when heartbeats stay silent:

if 23:00 < current_time < 08:00:
    if not urgent:
        return HEARTBEAT_OK  # Stay quiet

Proactive is good; waking someone at 3 AM for non-urgent news is not.

Track what's new

Avoid re-reporting the same information:

• Track last-seen message IDs
• Store timestamps of last checks
• Compare against previous state

Graceful degradation

If a data source is unavailable, don't fail the entire heartbeat:

try:
    check_email()
except EmailUnavailable:
    log("Email check failed, continuing")
    # Don't block other checks

Token efficiency

Heartbeats run frequently—optimize for token usage:

• Keep heartbeat prompts concise
• Use efficient context loading
• Summarize rather than include full documents

Both create scheduled agent behavior, but they serve different purposes:

Use heartbeats when:

• Checking multiple sources in one pass
• You need conversational context from recent messages
• Exact timing doesn't matter
• You want to reduce total API calls

Use cron when:

• Timing is exact ("9 AM every Monday")
• Task is standalone and specific
• You want isolation from main context
• Different model/configuration needed

Many systems use both: heartbeats for awareness, cron for scheduled tasks.

The watchdog Monitor for specific conditions, alert when triggered:

Heartbeat: Check system metrics
If any metric exceeds threshold → Alert
Else → HEARTBEAT_OK

The digest Accumulate information, summarize periodically:

Heartbeat: Collect new items
Every N heartbeats → Generate and send digest

The shepherd Check on running processes, intervene if needed:

Heartbeat: Check sub-agent status
If stuck or errored → Intervene or escalate
If complete → Process results
Else → HEARTBEAT_OK

The maintainer Perform incremental housekeeping:

Heartbeat: Review and organize
Clean old files, update indexes, prune logs
→ HEARTBEAT_OK

Real production agent systems (like Clawdbot/OpenClaw) use heartbeats extensively:

# HEARTBEAT.md

On heartbeat:
1. Check for urgent emails (starred or from VIP senders)
2. Review calendar for events in next 2 hours
3. Check notification queue
4. Review any pending tasks in memory/

If nothing urgent: HEARTBEAT_OK
If something needs attention: Notify via configured channel

Track check times in memory/heartbeat-state.json
Rotate through non-urgent checks (weather, news) across heartbeats
Respect quiet hours: 23:00-08:00 unless urgent

This pattern creates agents that feel genuinely helpful—catching things before they become problems, surfacing relevant information, and staying out of the way when nothing needs attention.