The Scheduler CLI enables 24/7 autonomous agent operations by running agents at regular intervals.

Quick Start

With Direct Prompt (No YAML needed)

# Schedule with a simple prompt
praisonai schedule "Check AI news and summarize" --interval hourly

With agents.yaml

# Schedule using agents.yaml configuration
praisonai schedule agents.yaml

Installation

pip install praisonai praisonaiagents
export OPENAI_API_KEY=your_key_here

PM2-Style Daemon Commands

Start Scheduler

With a Task Prompt

# Start as background daemon
praisonai schedule start <name> "Your task" --interval hourly

# With all options
praisonai schedule start my-agent "Monitor logs" \
  --interval "*/30m" \
  --timeout 120 \
  --max-cost 2.00 \
  --max-retries 3

# Examples
praisonai schedule start news-bot "Check AI news" --interval hourly
praisonai schedule start health-check "Monitor system" --interval "*/15m"
praisonai schedule start test-agent "Count to 5" --interval "*/10s"

With a Recipe

# Schedule a recipe
praisonai schedule start news-monitor --recipe news-analyzer --interval hourly

# Recipe with custom interval
praisonai schedule start daily-report --recipe report-generator --interval daily

# Recipe with all options
praisonai schedule start my-scheduler \
    --recipe my-recipe \
    --interval "*/6h" \
    --timeout 600 \
    --max-cost 2.00 \
    --max-retries 3

List Schedulers

# Show all running schedulers
praisonai schedule list

# Output example:
# Name                 Status     PID      Interval     Task
# ================================================================
# news-bot             🟢 running  12345    hourly       Check AI news
# health-check         🟢 running  12346    */15m        Monitor system
# 
# Total: 2 scheduler(s)

View Logs

# View last 50 lines
praisonai schedule logs <name>

# Follow logs in real-time
praisonai schedule logs <name> -f

# Examples
praisonai schedule logs news-bot
praisonai schedule logs news-bot --follow

Stop Scheduler

# Graceful shutdown
praisonai schedule stop <name>

# Example
praisonai schedule stop news-bot

Restart Scheduler

# Restart with same configuration
praisonai schedule restart <name>

# Example
praisonai schedule restart news-bot

Delete Scheduler

# Remove from list (must be stopped first)
praisonai schedule delete <name>

# Example
praisonai schedule delete news-bot

Describe Scheduler

# Show detailed information
praisonai schedule describe <name>

# Shows: PID, status, uptime, executions, cost, config, logs path

Legacy Foreground Mode

For quick testing or one-off runs, use foreground mode:

# Direct prompt (runs in foreground)
praisonai schedule "Your task" --interval hourly

# YAML mode (runs in foreground)
praisonai schedule agents.yaml

YAML Configuration Example:

framework: praisonai

agents:
  - name: "AI News Monitor"
    role: "Technology News Analyst"
    goal: "Monitor and summarize AI news"
    instructions: "Search for latest AI developments"
    tools:
      - search_tool
    verbose: true

task: "Search for latest AI news and provide top 3 stories"

schedule:
  interval: "hourly"
  max_retries: 3
  run_immediately: true
  timeout: 60
  max_cost: 1.00

Run YAML in foreground:

praisonai schedule agents.yaml

Press Ctrl+C to stop. Shows final statistics:

Execution stats - Total: 12, Success: 11, Failed: 1
Total cost: $0.0056
Runtime: 3600.5s

Storage Locations

Schedule data: ~/.praisonai/config.yaml (under the schedules key)
Log files: ~/.praisonai/logs/*.log

Schedules are stored in the same config.yaml used by agents and server configuration. Legacy jobs.json data is auto-migrated on first use.

Features

✅ PM2-style daemon management - No nohup needed
✅ Process persistence - State saved to disk
✅ Easy lifecycle control - start/stop/restart/list
✅ Centralized logging - Auto-rotation, follow mode
✅ Graceful shutdown - SIGTERM with SIGKILL fallback
✅ Cost monitoring - Budget limits with $1.00 default
✅ Timeout protection - Prevent runaway executions
✅ Auto cleanup - Dead processes removed automatically

Schedule Intervals

Format	Interval	Description
`hourly`	3600s	Every hour
`daily`	86400s	Every 24 hours
`*/30m`	1800s	Every 30 minutes
`*/6h`	21600s	Every 6 hours
`*/5s`	5s	Every 5 seconds (testing)
`3600`	3600s	Custom seconds

Examples

Example 1: Simple Prompt Scheduling

Quick news check every hour:

praisonai schedule "Search for latest AI news and summarize top 3 stories" --interval hourly --verbose

System monitoring every 15 minutes:

praisonai schedule "Check system health and disk space" --interval "*/15m"

With budget limit:

praisonai schedule "Analyze market trends" \
  --interval "*/30m" \
  --max-cost 0.50 \
  --timeout 120

Save Configuration

# Export scheduler config to YAML
praisonai schedule save <name> [output.yaml]

# Example
praisonai schedule save news-bot news-config.yaml

Command Reference

Daemon Commands

Command	Description	Example
`start <name> "task"`	Start scheduler as daemon	`praisonai schedule start my-bot "Task"`
`list`	List all schedulers	`praisonai schedule list`
`logs <name> [--follow]`	View logs	`praisonai schedule logs my-bot --follow`
`stop <name>`	Stop scheduler	`praisonai schedule stop my-bot`
`restart <name>`	Restart scheduler	`praisonai schedule restart my-bot`
`delete <name>`	Remove from list	`praisonai schedule delete my-bot`
`describe <name>`	Show details	`praisonai schedule describe my-bot`
`save <name> [file]`	Export to YAML	`praisonai schedule save my-bot config.yaml`

Options

Option	Type	Description	Default	Example
`--interval`	string	Schedule interval	`hourly`	`hourly`, `*/30m`, `daily`
`--max-retries`	int	Max retry attempts	`3`	`3`, `5`
`--timeout`	int	Max execution time (seconds)	`None`	`60`, `120`
`--max-cost`	float	Budget limit in USD	`$1.00`	`1.00`, `5.00`
`--verbose`, `-v`	flag	Enable verbose logging	`False`	-

Notes:

Default budget is $1.00 for safety. Set to higher value or null in YAML to disable.
Use --verbose to see detailed logs. Without it, output is clean for background running.

Example 2: News Monitoring with YAML (Advanced)

agents.yaml:

framework: praisonai

agents:
  - name: "AI News Monitor"
    role: "Technology News Analyst"
    instructions: "Search and summarize latest AI news"
    tools:
      - search_tool

task: "Search for latest AI news and provide top 3 stories"

schedule:
  interval: "hourly"
  max_retries: 3
  run_immediately: true

Run:

praisonai schedule agents.yaml

Example 2: Data Collection (Every 30 Minutes)

agents.yaml:

framework: praisonai

agents:
  - name: "Data Collector"
    role: "Data Analyst"
    instructions: "Collect and analyze market data"
    tools:
      - search_tool

task: "Collect latest market data and identify trends"

schedule:
  interval: "*/30m"
  max_retries: 5
  run_immediately: false

Run with override:

# Override to run every 15 minutes instead
praisonai schedule agents.yaml --interval "*/15m"

Example 3: With Budget and Timeout Limits

agents.yaml:

framework: praisonai

agents:
  - name: "Budget-Controlled Agent"
    role: "Worker"
    instructions: "Process data efficiently"
    tools:
      - search_tool

task: "Process and analyze data"

schedule:
  interval: "*/5m"
  max_retries: 3
  run_immediately: true
  timeout: 120              # Max 2 minutes per execution
  max_cost: 0.50            # Stop after $0.50 spent

Run:

praisonai schedule agents.yaml --verbose

Output:

Budget limit: $0.50
Timeout per execution: 120s
...
Estimated cost this run: $0.0002, Total: $0.0002
Budget remaining: $0.4998
...
Budget limit reached: $0.5001 >= $0.50
Stopping scheduler to prevent additional costs

Example 4: Testing with Short Interval

# Test with 10-second interval
praisonai schedule agents.yaml --interval "*/10s" --verbose

Python API

For programmatic control, use the Python API:

Option 1: Load from agents.yaml

from praisonai.scheduler import AgentScheduler

# Load from YAML
scheduler = AgentScheduler.from_yaml("agents.yaml")

# Start with YAML config
scheduler.start_from_yaml_config()

# Or override settings
scheduler = AgentScheduler.from_yaml(
    "agents.yaml",
    interval_override="*/15m",
    max_retries_override=5
)
scheduler.start_from_yaml_config()

# Keep running
try:
    while scheduler.is_running:
        import time
        time.sleep(1)
except KeyboardInterrupt:
    scheduler.stop()
    print(scheduler.get_stats())

Option 2: Create Programmatically

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

# Create agent
agent = Agent(
    name="NewsChecker",
    instructions="Check latest AI news",
    tools=[search_tool]
)

# Create scheduler
scheduler = AgentScheduler(
    agent=agent,
    task="Search for latest AI news"
)

# Start (runs every hour)
scheduler.start("hourly", max_retries=3, run_immediately=True)

# Keep running
try:
    while scheduler.is_running:
        import time
        time.sleep(1)
except KeyboardInterrupt:
    scheduler.stop()
    print(scheduler.get_stats())

Features

Core Features

Interval-based scheduling: Run agents at regular intervals
Background execution: Runs in daemon thread, won’t block terminal
Automatic retry: Retry failed executions with exponential backoff (30s, 60s, 90s)
Graceful shutdown: Clean stop with Ctrl+C
YAML configuration: Simple configuration in agents.yaml
CLI overrides: Override any setting from command line

Safety Features

⏱️ Timeout Protection: Prevent runaway executions (Unix/Linux/Mac only)
💰 Cost Monitoring: Real-time cost tracking with budget limits
📊 Statistics Tracking: Monitor execution success rates, costs, and runtime
🛡️ Budget Protection: Auto-stops when cost limit reached
🔄 Retry Logic: Exponential backoff prevents rapid failures

Output

The scheduler provides detailed logging with cost tracking:

Starting agent scheduler: AI News Monitor
Task: Search for latest AI news
Schedule: hourly (3600s interval)
Timeout per execution: 60s
Budget limit: $1.00
Agent scheduler started successfully

[2025-12-22 10:00:00] Starting scheduled agent execution
Attempt 1/3
Agent execution successful on attempt 1
Result: [agent output]
Estimated cost this run: $0.0001, Total: $0.0001
Budget remaining: $0.9999
Next execution in 3600 seconds (1.0 hours)

Statistics

Get execution statistics:

stats = scheduler.get_stats()
# Returns:
{
    "is_running": True,
    "total_executions": 10,
    "successful_executions": 9,
    "failed_executions": 1,
    "success_rate": 90.0,
    "total_cost_usd": 0.0045,
    "runtime_seconds": 3600.0,
    "cost_per_execution": 0.0005
}

On stop (Ctrl+C)

🛑 Stopping scheduler… 📊 Final Statistics: Total Executions: 5 Successful: 5 Failed: 0 Success Rate: 100.0% ✅ Agent stopped successfully

## Error Handling

The scheduler automatically retries failed executions with exponential backoff:

- **Attempt 1:** Execute immediately
- **Attempt 2:** Wait 30s, retry
- **Attempt 3:** Wait 60s, retry
- **Attempt 4:** Wait 90s, retry
- **Attempt 5:** Wait 120s, retry

## Stopping the Scheduler

Press `Ctrl+C` to stop gracefully. The scheduler will:
1. Set stop event
2. Wait for current execution (max 10s)
3. Log final statistics
4. Exit cleanly

## See Also

- [Planning Mode](/docs/cli/planning) - Add planning to scheduled agents
- [Memory](/docs/cli/memory) - Enable memory for scheduled agents
- [Tools](/docs/cli/tools) - Add custom tools to agents
- [Examples](https://github.com/MervinPraison/PraisonAI/tree/main/examples/python/scheduled_agents) - Working examples

CLI

​Quick Start

​With Direct Prompt (No YAML needed)

​With agents.yaml

​Installation

​PM2-Style Daemon Commands

​Start Scheduler

​With a Task Prompt

​With a Recipe

​List Schedulers

​View Logs

​Stop Scheduler

​Restart Scheduler

​Delete Scheduler

​Describe Scheduler

​Legacy Foreground Mode

​Storage Locations

​Features

​Schedule Intervals

​Examples

​Example 1: Simple Prompt Scheduling

​Save Configuration

​Command Reference

​Daemon Commands

​Options

​Example 2: News Monitoring with YAML (Advanced)

​Example 2: Data Collection (Every 30 Minutes)

​Example 3: With Budget and Timeout Limits

​Example 4: Testing with Short Interval

​Python API

​Option 1: Load from agents.yaml

​Option 2: Create Programmatically

​Features

​Core Features

​Safety Features

​Output

​Statistics

​On stop (Ctrl+C)

Quick Start

With Direct Prompt (No YAML needed)

With agents.yaml

Installation

PM2-Style Daemon Commands

Start Scheduler

With a Task Prompt

With a Recipe

List Schedulers

View Logs

Stop Scheduler

Restart Scheduler

Delete Scheduler

Describe Scheduler

Legacy Foreground Mode

Storage Locations

Features

Schedule Intervals

Examples

Example 1: Simple Prompt Scheduling

Save Configuration

Command Reference

Daemon Commands

Options

Example 2: News Monitoring with YAML (Advanced)

Example 2: Data Collection (Every 30 Minutes)

Example 3: With Budget and Timeout Limits

Example 4: Testing with Short Interval

Python API

Option 1: Load from agents.yaml

Option 2: Create Programmatically

Features

Core Features

Safety Features

Output

Statistics

On stop (Ctrl+C)