Built-in — no extra dependencies required. Schedule tools are included in the core praisonaiagents package.
Agent class are needed.
Quick Start
from praisonaiagents import Agent
from praisonaiagents.tools import schedule_add, schedule_list, schedule_remove
agent = Agent(
name="assistant",
instructions="You can set reminders and schedules for the user.",
tools=[schedule_add, schedule_list, schedule_remove],
)
agent.start("Remind me to check email every morning at 7am")
schedule_add with the appropriate schedule expression, and the job will be persisted to disk.
schedule_add
Add a new scheduled job.
| Parameter | Type | Required | Description |
|---|
name | str | Yes | Human-readable name (e.g. "morning-email-check") |
schedule | str | Yes | When to run (see Schedule Expressions) |
message | str | No | Prompt or reminder text to deliver when triggered |
schedule_list
List all scheduled jobs. Takes no parameters.
Returns: Formatted string listing every job with id, name, schedule, status, and message.
schedule_remove
Remove a scheduled job by name.
| Parameter | Type | Required | Description |
|---|
name | str | Yes | Name of the schedule to remove |
Schedule Expressions
| Format | Example | Description |
|---|
| Keyword | "hourly", "daily" | Predefined intervals |
| Interval | "*/30m", "*/6h", "*/10s" | Custom interval (minutes, hours, seconds) |
| Cron | "cron:0 7 * * *" | 5-field cron expression |
| One-shot | "at:2026-03-01T09:00:00" | ISO 8601 timestamp |
| Relative | "in 20 minutes" | Relative to now |
| Seconds | "3600" | Raw seconds |
Examples
Recurring Schedule
from praisonaiagents import Agent
from praisonaiagents.tools import schedule_add, schedule_list, schedule_remove
agent = Agent(
name="news-bot",
instructions="""You help users stay informed.
When asked, create schedules for news summaries.
Use schedule_add with cron expressions for precise timing.""",
tools=[schedule_add, schedule_list, schedule_remove],
)
# Agent will create: schedule_add("morning-news", "cron:0 7 * * *", "Summarize AI news")
agent.start("Send me an AI news summary every morning at 7am")
One-Shot Reminder
# Agent will create: schedule_add("meeting-prep", "in 20 minutes", "Prepare for standup")
agent.start("Remind me in 20 minutes to prepare for standup")
List and Manage
# Agent will call schedule_list() and schedule_remove("old-task")
agent.start("Show me my schedules and remove 'old-task'")
agent = Agent(
name="scheduler",
tools=["schedule_add", "schedule_list", "schedule_remove"],
)
Storage
Jobs are persisted to ~/.praisonai/schedules/jobs.json by default. The store is:
- Thread-safe for multi-agent scenarios
- Atomic writes (tmp + rename) to prevent corruption
- Auto-created on first use
Schedule Runner
The ScheduleRunner checks which jobs are due for execution:
from praisonaiagents.scheduler import ScheduleRunner, FileScheduleStore
store = FileScheduleStore()
runner = ScheduleRunner(store=store)
# Get jobs that are due right now
due_jobs = runner.get_due_jobs()
for job in due_jobs:
print(f"Due: {job.name} — {job.message}")
runner.mark_run(job) # Updates last_run_at
Hook Events
Schedule lifecycle events are available via the hook system:
| Event | When |
|---|
SCHEDULE_ADD | A new schedule is created |
SCHEDULE_REMOVE | A schedule is deleted |
SCHEDULE_TRIGGER | A scheduled job fires |
Architecture
Schedule tools follow PraisonAI’s core principles:
- Agent-centric — tools, not Agent parameters
- Lazy-loaded — zero import cost until used
- Protocol-driven —
FileScheduleStore is swappable
- No Agent bloat — the
Agent class is unchanged
- Thread-safe — safe for multi-agent workflows
