Scheduler Monitor

Turn a scheduled agent into a monitor: probe a cheap source each tick, run the model only when it changed, and stay silent when it didn’t.

The monitor field is a declarable spec the core round-trips through storage. The probe, hashing, bounded diff, state persistence, and the no_change record live in the praisonai-bot / wrapper layer — the core owns only the contract.

Quick Start

Turn an agent into a monitor

Add monitor to a ScheduleJob. The agent runs only when the watched URL changes.

from praisonaiagents import Agent
from praisonaiagents.scheduler import ScheduleJob, Schedule

agent = Agent(name="News watcher", instructions="Summarise new items")

job = ScheduleJob(
    name="hn-frontpage",
    schedule=Schedule(kind="every", every_seconds=900),
    message="Summarise the changes.",
    agent_id=agent.id,
    monitor={"url": "https://news.ycombinator.com/"},
)

Watch a shell source instead

Use command inside monitor to watch any cheap shell output — a file, a database count, a health probe.

from praisonaiagents.scheduler import ScheduleJob, Schedule

job = ScheduleJob(
    name="disk-watch",
    schedule=Schedule(kind="every", every_seconds=300),
    message="Explain the change in disk usage and flag anything urgent.",
    monitor={"command": "df -h /"},
)

What The User Sees

Silence is the feature — an unchanged source produces no ping and spends no tokens.

How It Works

Each tick probes the source, hashes the output, and compares it to the last-seen hash held in per-job state.

Tick outcome	What happens	Recorded status
Source unchanged	Model turn suppressed — no tokens, no delivery	`no_change`
Source changed	Bounded diff seeded into `message`, model runs once	`succeeded`
First run (no prior state)	Treated as changed — model runs, hash stored	`succeeded`
Probe errored	Prior state left untouched so a later recovery still suppresses	`failed`

no_change is a distinct status from skipped. skipped means “a gate said don’t run”; no_change means “a watched source was unchanged” — so operators can tell the two apart in run history.

Configuration Options

`monitor` spec

monitor is a small mapping naming one cheap source to probe each tick.

Key	Type	Description
`command`	`str`	Shell command whose stdout is hashed and diffed each tick
`url`	`str`	A bounded fetch whose response body is hashed and diffed each tick

`ScheduleJob` field

Field	Type	Default	Description
`monitor`	`Optional[Dict[str, Any]]`	`None`	Change-detection source spec. `None` keeps the existing stateless behaviour. Omitted from serialization when unset (fully backward-compatible)

`GateResult` — monitor outcome

The wrapper’s monitor gate returns a GateResult carrying the monitor-mode outcome.

Field	Type	Default	Description
`no_change`	`bool`	`False`	`True` when the watched source was unchanged. Suppressed silently and recorded as `no_change`. Implies `run=False` (enforced in `__post_init__`)
`state_updates`	`Optional[Dict[str, Any]]`	`None`	Bounded key/value to persist for the next tick (last-seen hash, watermark). `None` means “write nothing”

`RunRecord.status`

Value	Meaning
`succeeded`	The model turn ran and completed
`failed`	The run raised or the probe errored
`skipped`	A stateless gate said don’t run
`no_change`	A watched source was unchanged (monitor mode)

Monitor vs Pre-Run vs Command

Three scheduler features feel similar but solve different problems.

Feature	Kind	Fires the model?	Silence when…
`monitor`	Stateful (remembers last hash)	Only when the source changed	The source is unchanged (`no_change`)
`pre_run`	Stateless go/no-go gate	Only when the gate says “go”	Nothing to do (`skipped`)
`command`	Model-free delivery action	Never — delivers stdout verbatim	—

From the SDK docstring: “monitor is distinct from pre_run (a stateless go/no-go gate) and command (a model-free delivery action).”

On the scheduled delivery path, a no_change outcome is silently suppressed — no ping, no tokens. See Scheduler Delivery and Bot Intentional Silence for how unattended-monitor silence is enforced unconditionally.

Per-Job State

A monitor needs memory across wake-ups — the last-seen hash or a watermark. The core defines the JobStateStoreProtocol contract; a concrete store lives in the wrapper alongside the heavy monitor gate.

Method	Description
`get_state(job_id)`	Return the persisted state dict (`{}` if none)
`set_state(job_id, state)`	Persist bounded state for the job
`clear_state(job_id)`	Drop state when the job is removed

All JobStateStoreProtocol methods are optional. Callers detect support with hasattr() and treat absence as “no per-job state” — today’s stateless behaviour. Legacy stateless gates (should_run(self, job)) still satisfy the protocol under runtime_checkable, so callers must detect capability before passing state=.

Best Practices

Bound your source so a large fetch can't stall the tick

The probe runs on every tick. Watch a small, cheap source — a status endpoint, a row count, a file’s modification marker — not a multi-megabyte page. A bounded source keeps the ticker responsive.

monitor={"command": "curl -sf --max-time 5 https://status.example.com/health"}

Use monitor when you want silence-when-unchanged

Reach for monitor when the whole point is “only tell me when something changed” — a page, a feed, a metric. Unchanged ticks cost zero tokens and deliver nothing.

Use pre_run when you want silence-when-nothing-to-do

If the decision is a stateless go/no-go (an inbox check, a queue depth), use pre_run instead — it doesn’t need to remember a prior hash.

Let first-run seed the baseline

The first tick has no prior state, so it always runs and stores the baseline hash. Expect one delivery when a monitor job is created, then silence until the source moves.

Pre-Run Gate

Stateless go/no-go gate — skip when there’s nothing to do

Command Action

Model-free action — deliver a command’s stdout verbatim

Scheduler Delivery

Push scheduled results to Telegram/Discord/Slack/WhatsApp

Bot Intentional Silence

How unattended silence is enforced

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

What The User Sees

How It Works

Configuration Options

`monitor` spec

`ScheduleJob` field

`GateResult` — monitor outcome

`RunRecord.status`

Monitor vs Pre-Run vs Command

Per-Job State

Best Practices

Pre-Run Gate

Command Action

Scheduler Delivery

Bot Intentional Silence

​Quick Start

​What The User Sees

​How It Works

​Configuration Options

​monitor spec

​ScheduleJob field

​GateResult — monitor outcome

​RunRecord.status

​Monitor vs Pre-Run vs Command

​Per-Job State

​Best Practices

​Related

Pre-Run Gate

Command Action

Scheduler Delivery

Bot Intentional Silence

Quick Start

What The User Sees

How It Works

Configuration Options

`monitor` spec

`ScheduleJob` field

`GateResult` — monitor outcome

`RunRecord.status`

Monitor vs Pre-Run vs Command

Per-Job State

Best Practices

Related