Agent Scheduler

The Agent Scheduler is a timer-driven automation operator that repeatedly triggers a target action on a configurable schedule. It is most commonly used to call an Agent LOP at regular intervals, but can also pulse any parameter or execute a DAT. It includes rate limiting, cooldown periods, error recovery with exponential backoff, and call timeout handling.

Scheduling Modes

The scheduler supports three modes, set via the Mode menu on the Schedule page:

• Interval — Fires on a repeating timer. Set a Minimum and Maximum interval with a time Unit (seconds, minutes, or hours). Each cycle picks a random delay within that range, which is useful for avoiding predictable patterns.
• Daily (Time of Day) — Fires once at a specific Hour and Minute each day. Enable Repeat Daily to have it re-schedule automatically after each execution.
• Manual Only — No automatic scheduling. The scheduler only fires when you pulse Trigger Now or call Trigger() from a script.

Target Modes

The Target Mode menu determines what the scheduler triggers on each cycle:

• Agent (Call LOP) — Calls a LOPs Agent operator assigned to the Agent parameter. The scheduler waits for the agent’s response callback before completing the cycle.
• Pulse Parameter — Pulses any parameter on any operator. Set the Target OP and Pulse Par Name (e.g., Start). If the target has an Active parameter, the scheduler can optionally wait for it to go inactive before completing.
• Execute DAT — Runs a DAT’s contents via .run(). Useful for triggering arbitrary scripts on a schedule.

Wiring It Up

Basic Agent Schedule

1. Place an agent_scheduler and an agent in your network.
2. On the Schedule page, drag the agent operator onto the Agent parameter.
3. Set Mode to Interval and configure Minimum / Maximum to your desired range (e.g., 30-60 seconds).
4. Toggle Active on. The scheduler enters the waiting state and counts down to the first call.
5. Monitor progress on the Status page — it shows the current state, total calls, next call time, and error counts.

Pulse Mode Example

1. Set Target Mode to Pulse Parameter.
2. Assign any operator to Target OP and enter the parameter name in Pulse Par Name.
3. Enable Wait for Target if the target operator has an Active parameter and you want the scheduler to wait for it to finish before scheduling the next cycle.

Rate Limiting and Cooldown

On the Limits page, Max Consecutive Calls sets how many cycles can fire in a row before a mandatory cooldown. When the limit is hit, the scheduler enters the cooldown state for the configured Cooldown Duration before resuming.

Error Recovery

The scheduler tracks consecutive errors and provides two recovery strategies, configured on the Limits page:

• Retries per Cycle — How many times to retry a failed call before moving on to the next scheduled cycle. Each retry waits the Retry Delay before firing.
• Error Backoff After — After this many consecutive errors across cycles, the scheduler takes a longer break. The On Max Errors menu determines whether it enters an exponential backoff (using the Backoff Multiplier) or deactivates entirely.

Behavior Controls

• Wait for Target — When enabled, the scheduler waits for the target to finish before scheduling the next cycle. For Agent mode, this uses the agent’s response callback. For Pulse mode, it polls the target’s Active parameter.
• Hold — Pauses scheduling without deactivating. The scheduler enters the held state and resumes where it left off when Hold is turned off.
• Call Timeout — If a call takes longer than this (in seconds), the scheduler treats it as an error and follows the normal error recovery flow.

Callbacks

The scheduler fires five lifecycle callbacks through its Callback DAT. Use the Create Callbacks button on the Callbacks page to generate a template.

The most useful callback is onPreCall, which lets you veto a cycle by returning False. This is handy for adding custom conditions — for example, skipping a call if a certain sensor value is below a threshold, or injecting dynamic context into the agent before it runs.

onPostCall fires after each successful cycle and includes the response data (in Agent mode) and the call duration, which is useful for logging or triggering downstream actions.

onError provides the error type (config_error, call_error, api_error, timeout) and whether the scheduler will retry or has hit the error threshold, letting you add custom alerting or recovery logic.

Troubleshooting

• Scheduler stays in “calling” state — The target may not be responding. Check the Call Timeout value on the Limits page and ensure the target operator is functioning. Check the Status page for the Target State indicator.
• “No agent operator set” errors — Make sure the Agent parameter on the Schedule page has a valid Agent LOP assigned, not just any COMP.
• Calls fire too fast — Use Max Consecutive Calls and Cooldown Duration on the Limits page to throttle the scheduler. Even in Interval mode, setting a higher Minimum interval helps.
• Scheduler deactivated itself — This happens when On Max Errors is set to Deactivate and the error threshold is reached. Check the agent or target for persistent issues, then toggle Active back on or pulse Reset Stats on the Status page.

Parameters

Schedule

Status (Status) op('agent_scheduler').par.Status Str

Default:

"" (Empty String)

Schedule Header

Active (Active) op('agent_scheduler').par.Active Toggle

Default:

False

Agent (Agent) op('agent_scheduler').par.Agent COMP

Default:

"" (Empty String)

Mode (Mode) op('agent_scheduler').par.Mode Menu

Default:

interval

Options:

interval, daily, manual

Interval Settings Header

Minimum (Intervalmin) op('agent_scheduler').par.Intervalmin Float

Default:

0.0

Range:

0.1 to 86400

Slider Range:

0.1 to 86400

Maximum (Intervalmax) op('agent_scheduler').par.Intervalmax Float

Default:

0.0

Range:

0.1 to 86400

Slider Range:

0.1 to 86400

Unit (Intervalunit) op('agent_scheduler').par.Intervalunit Menu

Default:

seconds

Options:

seconds, minutes, hours

Daily Settings Header

Hour (0-23) (Dailyhour) op('agent_scheduler').par.Dailyhour Int

Default:

0

Range:

0 to 23

Slider Range:

0 to 23

Minute (0-59) (Dailyminute) op('agent_scheduler').par.Dailyminute Int

Default:

0

Range:

0 to 59

Slider Range:

0 to 59

Repeat Daily (Dailyrepeat) op('agent_scheduler').par.Dailyrepeat Toggle

Default:

False

Behavior Header

Wait for Agent (Waitforagent) op('agent_scheduler').par.Waitforagent Toggle

Default:

False

Hold (Hold) op('agent_scheduler').par.Hold Toggle

Default:

False

Manual Header

Trigger Now (Trigger) op('agent_scheduler').par.Trigger Pulse

Default:

False

Target Mode (Targetmode) op('agent_scheduler').par.Targetmode Menu

Default:

agent

Options:

agent, pulse, execute

Target OP (Targetop) op('agent_scheduler').par.Targetop COMP

Default:

"" (Empty String)

Pulse Par Name (Targetpulse) op('agent_scheduler').par.Targetpulse Str

Default:

"" (Empty String)

Execute DAT (Executedat) op('agent_scheduler').par.Executedat DAT

Default:

"" (Empty String)

Wait for Target (Waitfortarget) op('agent_scheduler').par.Waitfortarget Toggle

Default:

False

Limits

Rate Limiting Header

Max Consecutive Calls (Maxconsecutivecalls) op('agent_scheduler').par.Maxconsecutivecalls Int

Default:

0

Range:

0 to 1000

Slider Range:

0 to 1000

Cooldown Duration (Cooldownduration) op('agent_scheduler').par.Cooldownduration Float

Default:

0.0

Range:

0 to 86400

Slider Range:

0 to 86400

Cooldown Unit (Cooldownunit) op('agent_scheduler').par.Cooldownunit Menu

Default:

seconds

Options:

seconds, minutes, hours

Error Recovery Header

Retries per Cycle (Maxretries) op('agent_scheduler').par.Maxretries Int

Default:

0

Range:

0 to 10

Slider Range:

0 to 10

Retry Delay (sec) (Retrydelay) op('agent_scheduler').par.Retrydelay Float

Default:

0.0

Range:

0 to 300

Slider Range:

0 to 300

Error Backoff After (Maxconsecutiveerrors) op('agent_scheduler').par.Maxconsecutiveerrors Int

Default:

0

Range:

1 to 100

Slider Range:

1 to 100

On Max Errors (Erroraction) op('agent_scheduler').par.Erroraction Menu

Default:

backoff

Options:

backoff, deactivate

Backoff Multiplier (Errorbackoffmult) op('agent_scheduler').par.Errorbackoffmult Float

Default:

0.0

Range:

1 to 10

Slider Range:

1 to 10

Call Timeout (sec) (Timeoutsec) op('agent_scheduler').par.Timeoutsec Float

Default:

0.0

Range:

0 to 600

Slider Range:

0 to 600

Callbacks

Callbacks Header

Callback DAT (Callbackdat) op('agent_scheduler').par.Callbackdat DAT

Default:

"" (Empty String)

Print Callbacks (Printcallbacks) op('agent_scheduler').par.Printcallbacks Toggle

Default:

False

Create Callbacks (Createcallbacks) op('agent_scheduler').par.Createcallbacks Pulse

Default:

False

Status

Scheduler Status Header

State (State) op('agent_scheduler').par.State Str

Default:

"" (Empty String)

Total Calls (Callcount) op('agent_scheduler').par.Callcount Str

Default:

"" (Empty String)

Consecutive Errors (Consecutiveerrors) op('agent_scheduler').par.Consecutiveerrors Str

Default:

"" (Empty String)

Consecutive Calls (Consecutivecalls) op('agent_scheduler').par.Consecutivecalls Str

Default:

"" (Empty String)

Last Call (Lastcalltime) op('agent_scheduler').par.Lastcalltime Str

Default:

"" (Empty String)

Next Call (Nextcalltime) op('agent_scheduler').par.Nextcalltime Str

Default:

"" (Empty String)

Agent Active (Agentstate) op('agent_scheduler').par.Agentstate Str

Default:

"" (Empty String)

Reset Stats (Resetstats) op('agent_scheduler').par.Resetstats Pulse

Default:

False

Target State (Targetstate) op('agent_scheduler').par.Targetstate Str

Default:

"" (Empty String)

Callbacks

Available Callbacks:

• onPreCall
• onPostCall
• onError
• onCooldown
• onStateChange

Example Callback Structure:

def onPreCall(info):
# Called before each cycle fires. Return False to skip this call.
# info keys: call_count, time_since_last, consecutive_calls, mode, target_mode
# Agent mode also includes: agent
# Pulse mode also includes: target, pulse_par
# Execute mode also includes: target
pass

def onPostCall(info):
# Called after a successful cycle completes.
# info keys: response, full_response, callback_info, call_count, call_duration_s
pass

def onError(info):
# Called when a cycle fails.
# info keys: error, error_type, consecutive_errors, will_retry, hit_threshold
pass

def onCooldown(info):
# Called when rate limiting triggers a cooldown period.
# info keys: consecutive_calls, cooldown_duration_s
pass

def onStateChange(info):
# Called on every state transition (idle, waiting, calling, cooldown, held, error).
# info keys: old_state, new_state
pass

Changelog

v0.1.12026-03-01

• Rename CreateCallbacks to Createcallbacks to match parameter casing - Fix CreateCallbackDat skipping check when Callbackdat parameter already set
• Rename internal parameter callbacks to onPar prefix (Active, Hold, Mode, Resetstats, Createcallbacks) - Keep only public API methods promoted: Trigger, CreateCallbacks, Resetop - Add docstrings to public API methods - onParCreatecallbacks delegates to public CreateCallbacks
• Add generic target mode: agent, pulse parameter, or execute DAT - Pulse mode: pulse any parameter on any operator with optional wait-for-completion - Execute mode: run a DAT's contents via .run() on schedule - Poll target Active parameter for completion detection in pulse mode - Extract shared cycle helpers: _fire_precall, _begin_call, _on_target_complete - Rename agent-specific vars/pars to generic target names - Update callback template docs for all target modes - Mode-aware status labels and target state display
• Timer-driven agent scheduler with interval, daily, and manual modes - Rate limiting with configurable cooldown periods - Error recovery with retry logic and auto-deactivation - Call timeout handling via frame-driven schedule table - ChainedCallbacksExt callbacks: onPreCall, onPostCall, onError, onCooldown, onStateChange - Hold parameter for external pause control - manifest.json and README

Related Operators

• Agent
• Agent Orchestrator