Triggers

A trigger is what wakes an Agent up. Every Agent has at least one. Picking the right trigger is the difference between an Agent that's helpful and one that's noise.

The three kinds#

1. Event triggers (real time)#

The Agent listens to your Event Stream and runs when a specific event happens. This is what makes River feel ambient — the Agent acts the moment something relevant occurs, not later.

Common event triggers:

You can scope an event trigger — for instance, only fire email.received for emails matching a sender domain or labeled "Investors."

2. Schedule triggers (cron)#

The Agent runs on a recurring cadence. Cron expressions are supported, but most Schedules are written in plain language ("every weekday at 7am", "the first of each month").

Use a Schedule when:

• The work is predictable and time-bound (morning briefing, weekly recap, monthly billing summary)
• You want the result waiting for you when you sit down
• The data sources are reliable on a cadence

See Schedules for full options.

3. Manual triggers (on demand)#

The Agent only runs when you click Run now in the AutomationsApp, ask SpaceChat to invoke it, or call it via the API.

Use a manual trigger when:

• You're still iterating on the Agent
• The work is intermittent or context-dependent
• The user always wants to be in the loop

Most Agents support manual triggers in addition to their primary trigger — useful for testing and for rerunning after an edit.

Combining triggers#

A single Agent can have multiple triggers. The same Morning Briefer can:

• Run automatically every weekday at 7am (Schedule)
• Run when a new investor update arrives (Event)
• Run on demand from your assistant (Manual)

Each trigger fires independently. Each run is its own Job.

Choosing the right trigger#

Ask yourself: "What changes in the world that should make this Agent care?"

• If the answer is time → use a Schedule.
• If the answer is something specific happens → use an Event.
• If the answer is I haven't decided yet → use Manual until you do.

Avoiding noise#

The most common mistake is using too broad a trigger. email.received fires on every email — including newsletters, automated replies, and yourself. The Agent will burn through tokens triaging spam.

Always scope event triggers:

• Limit by sender, domain, or label
• Limit by entity type or Group
• Limit by time of day (some triggers support quiet hours)
• Add an early "is this relevant?" Skill in the Agent's persona to bail out fast on obvious non-matches

Tips#

• Start with manual triggers, get the Agent right, then move to events or schedules.
• Use the Job history to see how often your trigger fires — surprise volume is a sign it's too broad.
• When in doubt, add a "draft only" rule to the persona so a misfiring trigger doesn't ship something embarrassing.