Skip to main content

Triggers

A trigger runs your agent without a user typing anything — a webhook fires, a cron window opens, an event is emitted in your own code, and Svantic spins up a session and hands the agent a prompt. Triggers live on the Agent. Register them with agent.add_triggers() before calling attach() or agent.start().

The shape of a trigger

Every trigger has a type, a prompt template, and the fields its kind requires:
The three kinds — webhook, schedule, emit — are covered below. See the RuntimeTrigger reference for every field.

Prompt templates

Prompts are regular strings with {{placeholders}}:
At dispatch time, placeholders are replaced with values from the trigger’s payload. For webhook triggers with nested payloads, use payload_map to extract values with dot-notation before interpolation:
Unknown placeholders are left as-is ({{key}}) so they’re easy to spot in logs.

Webhooks

attach mounts app.post(trigger.path, …) and fires the prompt with the request body as the payload:
Hook Stripe (or anything else) at https://your-app.com/hooks/stripe. The webhook responds 200 { status: 'accepted' } immediately — trigger handling runs in the background. Any thrown error surfaces as a 500 with the error message. The webhook is an ordinary Express route, so any middleware you’ve installed (express.json(), auth, rate limiting) applies.

Schedules

Cron expressions, standard 5-field: minute hour day-of-month month day-of-week.
Supported syntax: *, single values, comma lists (0,15,30,45), ranges (9-17), steps (*/15), weekday names (MONSUN). Timezone is the process’s local timezone — set TZ in your deploy environment to control it. The scheduler checks every minute; cron expressions finer than one-minute granularity collapse to minute precision. Schedules don’t carry a payload — every run sees payload = {}. Use static prompts or interpolate values you inject via on_trigger.

Emit events

Event-driven triggers listen on an in-process bus. Fire them with handle.emit(event, payload) or handle.ask(event, payload).
Use ask when you want the trigger’s result back (rejects after 30 s):

Custom dispatch

By default, triggers create a Svantic session and send the prompt to the agent. Override with agent.on_trigger when you want different routing — for example, calling a specific capability directly:
The callback receives a context object with prompt, trigger, payload, and mesh. Return { skip: true } to block delivery, { prompt: 'override' } to change the prompt, or { metadata: {...} } to attach metadata.

Where triggers live

Register triggers on the agent with agent.add_triggers() — this is the canonical place. Forge scaffolds generate a triggers.ts file next to the agent that calls add_triggers for you. You can also hand-write them — they’re plain TypeScript values.

See also