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

​
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:
FormatExampleDescription
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

ParameterTypeDefaultDescription
schedulestr"hourly"When to run (see table above)
promptstrNoneOverride prompt for each tick (None = “Run your scheduled check.”)
on_resultCallableNoneCallback receiving result text. None = log to stdout
on_errorstr|Callable"retry""retry", "skip", or callable(error)
max_retriesint3Max consecutive retries before skipping

​
Error Handling

​
Best Practices

Call hb.start(blocking=False) to run in a daemon thread alongside your web server or bot.
Without on_result, results are only logged. Connect it to Slack, email, or a database for production use.
For long-running heartbeats, enable loop_detection=True on the agent to prevent stuck states.

Schedule Tools

Agent-centric scheduling via tool calls

Background Tasks

BackgroundRunner and ScheduleLoop