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.
Python
from praisonaiagents import Agent, Heartbeat
agent = Agent(instructions="Check server status and summarize")
hb = Heartbeat(agent, schedule="hourly", prompt="Report system health")TypeScript
import { Agent, Heartbeat } from 'praisonai';
const agent = new Agent({ instructions: 'Check server status and summarize' });
const hb = new Heartbeat(agent, { schedule: 'every 30m', prompt: 'Report system health' });In TypeScript the schedule accepts the same keywords (hourly, daily, weekly) plus intervals with an optional "every " prefix (every 30m, 30m, every 6h). onError is "retry" | "skip" or a callback, and maxRetries defaults to 3.
The user configures a schedule; the heartbeat runs the agent and delivers results via callback.
How It Works
Quick Start
- Basic Heartbeat
python 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 - With Callback
python 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() - Background Thread
python 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.