Heartbeat

Run agents on a schedule and deliver results via callbacks

Heartbeat runs an agent on a recurring schedule and delivers the results via callbacks. Standalone — does NOT modify the Agent class.

from praisonaiagents import Agent, Heartbeat

agent = Agent(instructions="Check server status and summarize")
hb = Heartbeat(agent, schedule="hourly", prompt="Report system health")

The user configures a schedule; the heartbeat runs the agent and delivers results via callback.

How It Works

Quick Start

1. Basic Heartbeat

   from praisonaiagents import Agent, Heartbeat
   
   agent = Agent(instructions="Check server status and summarize")
   hb = Heartbeat(agent, schedule="hourly")
   hb.start()  # Blocks — runs agent every hour
   
2. With Callback

   from praisonaiagents import Agent, Heartbeat
   
   agent = Agent(instructions="Summarize latest news")
   
   def send_to_slack(result):
       print(f"📬 {result}")
   
   hb = Heartbeat(
       agent,
       schedule="every 30m",
       prompt="Give me a 3-bullet news summary",
       on_result=send_to_slack,
   )
   hb.start()
   
3. Background Thread

   hb = Heartbeat(agent, schedule="daily")
   hb.start(blocking=False)  # Runs in daemon thread
   # ... your app continues running
   hb.stop()
   

---

Schedule Expressions

Heartbeat uses the same schedule parser as Schedule Tools:

Format	Example	Description
Keyword	"hourly", "daily", "weekly"	Predefined intervals
Interval	"every 30m", "every 6h", "*/10s"	Custom interval
Cron	"cron:0 7 * * *"	5-field cron expression
One-shot	"at:2026-03-01T09:00:00"	ISO 8601 timestamp

---

Configuration

Parameter	Type	Default	Description
schedule	str	"hourly"	When to run (see table above)
prompt	str	None	Override prompt for each tick (None = “Run your scheduled check.”)
on_result	Callable	None	Callback receiving result text. None = log to stdout
on_error	str|Callable	"retry"	"retry", "skip", or callable(error)
max_retries	int	3	Max consecutive retries before skipping

---

Error Handling

---

Best Practices

Use Background Mode for Web Apps

Call hb.start(blocking=False) to run in a daemon thread alongside your web server or bot.

Always Set on_result in Production

Without on_result, results are only logged. Connect it to Slack, email, or a database for production use.

Combine with Loop Detection

For long-running heartbeats, enable loop_detection=True on the agent to prevent stuck states.

---

Related

Schedule Tools

Agent-centric scheduling via tool calls

Background Tasks

BackgroundRunner and ScheduleLoop