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

Deliver Scheduled Results to a Chat Channel

Route each successful scheduled run to Telegram, Discord, Slack, or WhatsApp — no gateway required. Set a deliver token from Python, YAML, or the CLI:

Python
YAML
CLI

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(name="Briefer", instructions="Summarise this morning's news in 5 bullets.")
AgentScheduler(agent, task="Morning brief", deliver="telegram:123456").start("every 1h")

schedule:
  every: "1h"           # alias for `interval`
  deliver: "telegram:123456"

praisonai schedule agent.yaml --interval 1h --deliver telegram:123456
# or
praisonai schedule agent.yaml -i 1h -d telegram:123456

Token Grammar

The deliver token uses DeliveryTarget.parse. Whitespace is stripped and origin/all are case-insensitive.

Token	Meaning
`""` / omitted	No delivery (default)
`telegram`	Platform’s home channel (router resolves)
`telegram:123456`	Explicit channel
`telegram:123:789`	Explicit channel + thread
`origin` / `all`	Symbolic — requires the full BotOS gateway; not resolvable from the lightweight scheduler path (logs a clear warning)

Optional Dependency

Delivery goes through the praisonai-bot package.

pip install "praisonai[bot]"

If it isn’t installed, the scheduled run still succeeds — a single warning is logged and delivery is a no-op.

A CLI --deliver token overrides any target resolved from YAML or a recipe.

origin and all need the request session context and every configured bot respectively, so they only resolve under the full BotOS gateway. On the lightweight scheduler path they log a warning and skip delivery — use an explicit platform or platform:channel_id token instead.

Async Delivery

AsyncAgentScheduler accepts the same deliver= parameter and dispatches delivery through asyncio.to_thread because the shared helper uses the sync bridge — it never raises and never blocks the event loop.

import asyncio
from praisonaiagents import Agent
from praisonai.scheduler import AsyncAgentScheduler

async def main():
    agent = Agent(name="Briefer", instructions="Summarise today's AI news in 5 bullets.")
    scheduler = AsyncAgentScheduler(agent=agent, task="Morning brief", deliver="telegram:123456")
    await scheduler.start("hourly")

asyncio.run(main())

Delivery Best Practices

Prefer platform:channel_id for reliable routing

A bare platform token depends on the router resolving the platform’s home channel. Use telegram:123456 to target an explicit chat and avoid ambiguity.

Keep the token in YAML for reproducibility

Store schedule.deliver in YAML so scheduled jobs are reproducible. Override with -d only for one-off runs.

Don't use origin / all on the lightweight path

origin and all require the full BotOS gateway. Setting them on the lightweight scheduler path logs a warning and skips delivery.

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
# Note: Async daemons (schedule start) now correctly persist executions and cost to disk (PR #1857)

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
`weekly`	604800s	Every 7 days
`*/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`, `daily`, `weekly`, `*/30m`
`--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`
`--deliver`, `-d`	string	Deliver each result to a chat target (overrides YAML/recipe)	`""`	`telegram:123456`, `telegram`
`--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
...
Run cost: $0.0034 (model=gpt-4o-mini, in=2100, out=480). Total: $0.0034 / $0.5
...
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 async-native Python API:

Async Agent Scheduler (Recommended)

import asyncio
from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

async def main():
    # Create agent
    agent = Agent(
        name="NewsChecker",
        instructions="Check latest AI news",
    )

    # Create scheduler using canonical import
    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:
        import time
        time.sleep(3600)  # Run for 1 hour
    except KeyboardInterrupt:
        pass
    finally:
        scheduler.stop()
        stats = scheduler.get_stats()
        print(f"Executions: {stats['execution_count']}, Success: {stats['success_count']}")

asyncio.run(main())

Import paths (PR #1552):

Canonical: from praisonai.scheduler import AgentScheduler
Deprecated (still works, emits DeprecationWarning): from praisonai.agent_scheduler import AgentScheduler
Pending deprecation (still works, emits PendingDeprecationWarning — will move to praisonai.scheduler.async_agent_scheduler in a future release): from praisonai.async_agent_scheduler import AsyncAgentScheduler

The canonical AgentScheduler from praisonai.scheduler exposes from_yaml, start_from_yaml_config, and from_recipe. For new applications, prefer AsyncAgentScheduler which provides better cancellation and fits naturally into async codebases.Budget & timeout (PR #1771): AsyncAgentScheduler now accepts timeout (per-run seconds) and max_cost (total USD cap) in its constructor — see Async Agent Scheduler for the full pattern.MCP scheduling note: The MCP server’s praisonai.schedule.list / .add / .remove tools are now backed by praisonaiagents.tools.schedule_tools, so YAML/recipe scheduling works through MCP without needing to choose an import path.Async-only agents (PR #2147): The sync AgentScheduler now accepts agents that expose only astart() (not start()). Dispatch logic is shared between sync and async schedulers via praisonai.scheduler._dispatch.adispatch_agent. Both schedulers prefer astart() when present and fall back to start() in a worker thread.

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(
    name="NewsChecker",
    instructions="Check the latest AI news",
)

# Sync scheduler now runs agents that only expose astart()
scheduler = AgentScheduler(agent=agent, task="Summarise top 3 AI stories")
scheduler.start("hourly", max_retries=3, run_immediately=True)

Features

Core Features

Interval-based scheduling: Run agents at regular intervals
Background execution: Runs in daemon thread, won’t block terminal
Automatic retry: Exponential backoff + jitter, capped at 300s, shared between sync & async
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
💰 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

Real cost tracking (PR #2171): --max-cost is now enforced against the real per-token spend pulled from each agent response. Previously the scheduler added a fixed $0.0001 per run, so the default $1.00 brake required ~10,000 executions to trip. Set --max-cost to your actual budget, and ensure your model is in DEFAULT_PRICING (or register it — see Cost Tracking) so runs aren’t silently priced at $0.

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]
Run cost: $0.0034 (model=gpt-4o-mini, in=2100, out=480). Total: $0.0034 / $1.0
Next execution in 3600 seconds (1.0 hours)

Callbacks

Both schedulers accept on_success and on_failure callbacks in the constructor. Callbacks may be sync or async functions; a raising callback is logged and swallowed — it will not stop the scheduler.

on_success(result) — called with the agent’s return value after a successful run.
on_failure(exc) — called with the final Exception after all retries are exhausted. (Previously sync passed a formatted string; as of PR #1474 both sync and async pass the exception object.)

def success_callback(result):
    print(f"Success: {result}")

def failure_callback(exception):
    print(f"Failed: {exception}")

scheduler = AgentScheduler(
    agent=agent,
    task="Check news",
    on_success=success_callback,
    on_failure=failure_callback
)

Statistics

CLI Daemon: Use praisonai schedule describe <name> for detailed stats Python API (AsyncAgentScheduler):

stats = await scheduler.get_stats_async()
# Returns:
{
    "is_running": True,
    "total_executions": 10,
    "successful_executions": 9,
    "failed_executions": 1,
    "success_rate": 90.0,
    "total_cost_usd": 0.0234,
    "remaining_budget": 0.9766,
    "runtime_seconds": 3601.5,
    "cost_per_execution": 0.0023,
}

Stats parity (PR #1857): Both AgentScheduler and AsyncAgentScheduler now return the same stats shape via a shared _BaseAgentScheduler._build_stats() helper. Keys: is_running, total_executions, successful_executions, failed_executions, success_rate, total_cost_usd, remaining_budget, runtime_seconds, cost_per_execution. Use await scheduler.get_stats_async() in async code, scheduler.get_stats() in sync code.

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 retries failed executions with exponential backoff + jitter:

- **Attempt 1:** Run immediately.
- **On failure:** Wait `backoff_delay(attempt)` seconds, then retry.
- Delay formula: `min(max(30, 2 ** attempt), 300)` seconds, with ±10% jitter.
- **Cap:** 300s between attempts. **Floor:** ~27s.
- Sync and async schedulers now share the same `backoff_delay()` implementation as of [PR #1673](https://github.com/MervinPraison/PraisonAI/pull/1673), not just the same formula.

`max_retries` is the **total** number of attempts (including the first run).
`max_retries=3` → 1 initial attempt + up to 2 retries.

## Stopping the Scheduler

### Interruptible backoff (PR #1673)

Calling `scheduler.stop()` during a retry backoff window now returns within milliseconds. Previously a stop signal could wait out the full backoff delay (up to ~300s).

### Cross-platform timeout (PR #1741)

Execution timeouts now work on all platforms including Windows and can run safely in worker threads (FastAPI background tasks, the bot adapter, Streamlit). Previously timeouts were Unix/Linux/Mac only and failed in worker thread contexts.

```python
import signal
from praisonai.scheduler import AgentScheduler

scheduler = AgentScheduler(agent, "Monitor logs")
scheduler.start("hourly", max_retries=3)

# Set up signal handler
def handle_sigint(signum, frame):
    print("Ctrl+C pressed - stopping scheduler...")
    scheduler.stop()  # Returns immediately, even during backoff
    exit(0)

signal.signal(signal.SIGINT, handle_sigint)

CLI Commands

Use the daemon management commands:

# Graceful shutdown
praisonai schedule stop <name>

# Force kill if needed
praisonai schedule delete <name>

Python API

# Graceful async shutdown
await scheduler.stop()  # Waits up to 30s for current execution

Foreground Mode

Press Ctrl+C to stop gracefully. The scheduler will:

Set stop event
Wait for current execution to complete
Log final statistics
Exit cleanly

​Quick Start

​With Direct Prompt (No YAML needed)

​With agents.yaml

​Installation

​Deliver Scheduled Results to a Chat Channel

​Token Grammar

​Optional Dependency

​Async Delivery

​Delivery Best Practices

​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

​Async Agent Scheduler (Recommended)

​Features

​Core Features

​Safety Features

​Output

​Callbacks

​Statistics

​On stop (Ctrl+C)

​CLI Commands

​Python API

​Foreground Mode

​See Also

Quick Start

With Direct Prompt (No YAML needed)

With agents.yaml

Installation

Deliver Scheduled Results to a Chat Channel

Token Grammar

Optional Dependency

Async Delivery

Delivery Best Practices

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

Async Agent Scheduler (Recommended)

Features

Core Features

Safety Features

Output

Callbacks

Statistics

On stop (Ctrl+C)

CLI Commands

Python API

Foreground Mode

See Also