Scheduler Providers

A scheduler provider decides when to fire. The default polls in-process; swap it for systemd, a cloud scheduler webhook, or a cron trigger without changing what fires. A provider never decides what fires — it just calls on_due whenever a tick should occur, and the shared runner and store claim and fire due jobs.

Which Provider?

Pick in-process when one host runs all the time; pick an external provider when firing should come from elsewhere.

Quick Start

Default — in-process poll (nothing to configure)

from praisonaiagents import Agent
from praisonaiagents.scheduler import ScheduleLoop

agent = Agent(name="assistant", instructions="You set reminders.")

loop = ScheduleLoop(on_trigger=lambda job: agent.start(job.message))
loop.start()  # zero-arg — same as before

External / serverless — event-driven, no always-on thread

from praisonaiagents import Agent
from praisonaiagents.scheduler import ScheduleLoop

agent = Agent(name="assistant", instructions="You set reminders.")

# Reuse the built-in loop as a pure "claim + fire" engine — do NOT call start().
engine = ScheduleLoop(on_trigger=lambda job: agent.start(job.message))

# In your webhook / cron / systemd-timer handler:
def on_cloud_scheduler_ping():
    engine.fire_due()  # one tick — no daemon thread

How It Works

The provider owns the trigger; the runner and store own the firing. on_due is the seam: the provider calls it whenever its trigger fires, and everything downstream — claiming due jobs and firing them — happens in the runner and store.

Piece	Owns
Provider (`SchedulerProviderProtocol`)	When a tick happens
`ScheduleRunner` + store	What is due and how it fires

Provider Options

Two ways to drive firing — one always-on, one event-driven.

Provider	When to use	Always-on thread?
`InProcessScheduleProvider` (default, alias for `ScheduleLoop`)	Single always-on process	Yes (daemon)
External (webhook / systemd / cron / K8s CronJob / APScheduler)	Multi-host, serverless, or delegate to existing scheduler	No

Any object with start(on_due, store=...) and stop() satisfies SchedulerProviderProtocol.

from praisonaiagents.scheduler import (
    SchedulerProviderProtocol,
    InProcessScheduleProvider,
    ScheduleLoop,
)

assert InProcessScheduleProvider is ScheduleLoop
assert isinstance(ScheduleLoop(on_trigger=lambda job: None), SchedulerProviderProtocol)

User Interaction Flow

A reminder set through the agent still fires even when a cloud scheduler drives the tick.

Configuration Options

Providers are protocol-only — see the auto-generated SDK reference for full signatures.

Scheduler Protocols

SchedulerProviderProtocol, ScheduleStoreProtocol, JobConditionProtocol, GateResult

Schedule Tools

Agent-callable schedule_add / schedule_list / schedule_remove

Common Patterns

Cloud webhook

Cloud Scheduler, EventBridge, or a GitHub Actions cron posts to an HTTP handler that calls fire_due().

from praisonaiagents import Agent
from praisonaiagents.scheduler import ScheduleLoop

agent = Agent(name="assistant", instructions="You set reminders.")
engine = ScheduleLoop(on_trigger=lambda job: agent.start(job.message))

# e.g. FastAPI / Flask route the cloud scheduler pings on a schedule
def handle_scheduler_webhook():
    engine.fire_due()
    return {"ok": True}

systemd / launchd timer

A timer unit runs a short command on schedule; the command fires one tick and exits.

# fire_once.py — invoked by a systemd timer (OnCalendar=*:0/5)
from praisonaiagents import Agent
from praisonaiagents.scheduler import ScheduleLoop

agent = Agent(name="assistant", instructions="You set reminders.")
ScheduleLoop(on_trigger=lambda job: agent.start(job.message)).fire_due()

Kubernetes CronJob

A short-lived pod runs fire_due() and exits — no long-running scheduler pod.

# entrypoint.py — the CronJob pod's command
from praisonaiagents import Agent
from praisonaiagents.scheduler import ScheduleLoop

agent = Agent(name="assistant", instructions="You set reminders.")
ScheduleLoop(on_trigger=lambda job: agent.start(job.message)).fire_due()

Best Practices

Never call start() twice on the same loop

start() on a running loop is a no-op by design. Treat one loop as one provider — don’t try to reconfigure it mid-run.

Use fire_due() directly for serverless

In webhook, cron, or systemd handlers call engine.fire_due() and never call start() — you get one tick’s work with no daemon thread.

Concurrency is safe by default

fire_due() runs its claim + fire step under a per-instance lock, so an external caller and the loop thread can’t double-fire on non-atomic stores.

Pair external providers with claim_due stores

When firing from multiple hosts, use a store that implements claim_due for cross-host at-most-once delivery.

Background Tasks — ScheduleLoop

The in-process poll loop and combined recipes

Schedule Tools

Let agents create schedules via tool calls

Scheduled Run Policy

Safety gate for unattended scheduled runs

Scheduler Pre-Run Gate

Skip ticks cheaply before spending tokens

Scheduler Delivery

Scheduled Run Policy

​Which Provider?

​Quick Start

​How It Works

​Provider Options

​User Interaction Flow

​Configuration Options

Scheduler Protocols

Schedule Tools

​Common Patterns

​Cloud webhook

​systemd / launchd timer

​Kubernetes CronJob

​Best Practices

​Related

Background Tasks — ScheduleLoop

Schedule Tools

Scheduled Run Policy

Scheduler Pre-Run Gate

Which Provider?

Quick Start

How It Works

Provider Options

User Interaction Flow

Configuration Options

Common Patterns

Cloud webhook

systemd / launchd timer

Kubernetes CronJob

Best Practices

Related