Agents: Watchers & Schedulers

Agents are BunkerAI-powered automations that run on your broker. Set up reactive monitoring with Watchers (fire when a topic condition is met) and time-based automation with Scheduled Jobs (publish on a cron schedule) - no code required.

Two Types of Agents

• Watcher - monitors a topic and fires an action when a condition is met
• Scheduled Job - publishes a message to a topic on a cron schedule

Watchers

What a Watcher Does

A Watcher subscribes to an MQTT topic on your broker and continuously evaluates incoming messages against a condition you define. When the condition is met, the Watcher fires a configured response and logs the event.

Watchers are ideal for:

• Detecting when sensor readings cross a threshold
• Alerting when a device publishes an unexpected value
• Monitoring heartbeat topics for missed messages
• Detecting state changes on actuators or switches

Creating a Watcher

1. Navigate to Tools > Agents in the sidebar.
2. Click Add Watcher.
3. Configure the fields:

• Topic - the MQTT topic to watch. Can be a specific topic (sensor/temp/kitchen) or a pattern (sensor/+/temp).
• Condition Operator - how to compare the incoming value: >, <, =, !=, >=, <=, or contains.
• Condition Value - the threshold or value to compare against (e.g., 35, "error", "offline").
• Response Template - a message logged when the watcher fires. You can reference the triggering message value in the template.
• One-shot vs Continuous - whether the watcher fires once and stops, or continues firing every time the condition is met.
• Cooldown - for continuous watchers, the minimum time between firings in seconds (prevents alert flooding).

4. Click Save. The Watcher starts immediately.

One-Shot vs Continuous Watchers

One-shot: the watcher fires once when the condition is first met, then automatically disables itself. Use for "fire and forget" scenarios, like sending a one-time alert when a device reports a critical value.

Continuous: the watcher keeps watching and fires every time a new message satisfies the condition, subject to the cooldown. Use for ongoing monitoring like high temperature alerts.

Cooldown Settings

The cooldown prevents alert flooding when a condition stays true for an extended period. If sensor/temp/kitchen is above 35C and the device publishes every 10 seconds, a watcher with no cooldown fires every 10 seconds. Set a 300-second cooldown to cap it at once every 5 minutes.

Watcher Events Log

Every time a Watcher fires, an event is logged with the timestamp, triggering topic, payload value, and which watcher fired. View the event log from the Agents page. Events also trigger the real-time bell notification in the BunkerM header.

Example: Temperature Watcher

Get an alert whenever the kitchen temperature sensor reports above 35C:

Topic:     sensor/temp/kitchen
Condition: > 35
Response:  Kitchen temperature exceeded 35C - current value: {value}
Mode:      Continuous
Cooldown:  600 seconds

Scheduled Jobs

What a Scheduled Job Does

A Scheduled Job publishes an MQTT message to a specified topic on a cron schedule. It runs automatically in the background. Use Scheduled Jobs for:

• Heartbeat messages to verify your broker is alive
• Periodic configuration updates to devices
• Timed commands (turn off lights at midnight, run a daily report)
• Test message injection during development

Creating a Scheduled Job

1. Navigate to Tools > Agents in the sidebar.
2. Click Add Scheduled Job.
3. Configure the fields:

• Description - a human-readable name (e.g., "Daily heartbeat", "Midnight light off").
• Cron Expression - when the job runs. Standard 5-field cron format: minute hour day-of-month month day-of-week.
• Topic - the MQTT topic to publish to.
• Payload - the message content to publish.
• QoS - Quality of Service level (0, 1, or 2).
• Retain - whether the broker should retain this message.

4. Click Save. The job is scheduled immediately.

Cron Expression Examples

* * * * *       Every minute
0 * * * *       Every hour (at the top of the hour)
0 8 * * *       Every day at 8:00 AM
0 8 * * 1       Every Monday at 8:00 AM
0 0 1 * *       First day of every month at midnight
*/5 * * * *     Every 5 minutes
0 8,18 * * *    Every day at 8 AM and 6 PM

Example: Heartbeat Publisher

Publish a heartbeat every minute so downstream systems know the broker is alive:

Description: Broker heartbeat
Cron:        * * * * *
Topic:       system/heartbeat
Payload:     {"status": "alive", "source": "bunkerm"}
QoS:         0
Retain:      true

Community Plan Limits

On the Community (free) plan, you can create a maximum of 2 agents total across Watchers and Scheduled Jobs combined. Connect a paid BunkerAI plan to create more agents.

Real-Time Event Notifications

When a Watcher fires, a notification appears on the bell icon in the BunkerM header. Click the bell to see recent watcher events without navigating to the Agents page. This lets you stay aware of broker activity at a glance from anywhere in the dashboard.