Set a Trigger to Run an Agent Cycle

A trigger decides when your agent runs a cycle. You set one trigger per data-defined agent (DDA), and you choose from three types depending on what should start the work:

  • Interval: Run on a fixed time interval.

  • Cron: Run on a schedule.

  • MQTT: Run each time a message arrives on a topic.

You define the trigger in the trigger block of your agent configuration.

Interval

Run the agent on a fixed time interval.

trigger:
  type: interval
  intervalMs: 30000 # Run every 30 seconds
  immediate: true # Also run once immediately at startup
Field Required Default Description

type

Yes

None

interval

intervalMs

Yes

None

Interval in milliseconds

immediate

No

false

Run once at startup before waiting for the first interval

When to use: Regular polling of sensors, databases, or APIs where a fixed frequency is right.

Cron

Run the agent on a schedule using a cron expression.

trigger:
  type: cron
  cronExpression: '0 */6 * * *' # Every 6 hours
Field Required Description

type

Yes

cron

cronExpression

Yes

Standard cron expression (5 fields: minute, hour, day, month, weekday)

Common expressions:

Expression Meaning

* * * * *

Every minute

0 * * * *

Every hour

0 */6 * * *

Every 6 hours

0 8 * * 1-5

Weekdays at 08:00

0 0 * * *

Daily at midnight

0 0 * * 0

Weekly on Sunday

When to use: Scheduled reporting, daily summaries, shift-change analysis, or any job that runs at a specific time.

MQTT Trigger

Start a cycle each time a message arrives on a subscribed topic.

trigger:
  type: mqtt
  connection: factory-mqtt # Name from your connections: block
  topic: factory/events/alarm # MQTT wildcards (+ and #) are supported
Field Required Description

type

Yes

mqtt

connection

Yes

Name of an MQTT connection from your connections: block

topic

Yes

MQTT topic to subscribe to

The message that triggered the cycle is available in the Sense stage as part of environmentalData. You do not need a separate MQTT sense substage to access the triggering message.

When to use: Agents that need to react immediately to specific events (alarms, state changes, device alerts) rather than polling on a schedule.

Choosing a Trigger

Scenario Trigger type

Regular polling (sensors, databases)

interval

Scheduled reports or summaries

cron

Immediate reaction to MQTT events

mqtt