Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.svantic.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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: 
import type { RuntimeTrigger } from '@svantic/sdk';

const triggers: RuntimeTrigger[] = [
  /* … */
];
The three kinds — webhook, schedule, emit — are covered below. See the RuntimeTrigger reference for every field.

​
Prompt templates

Prompts are regular strings with {{placeholders}}: 
prompt: 'A new order came in for {{amount}} from {{customer}}.'
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: 
{
  type: 'webhook',
  path: '/hooks/stripe',
  prompt: 'A payment of {{amount}} just cleared for {{customer}}.',
  payload_map: {
    amount: 'data.object.amount_total',
    customer: 'data.object.customer_email',
  },
}
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: 
agent.add_triggers([
  {
    type: 'webhook',
    path: '/hooks/stripe',
    prompt: 'Payment {{id}} of {{amount}} cents just settled; update the order.',
    payload_map: {
      id: 'data.object.id',
      amount: 'data.object.amount_total',
    },
  },
]);

await attach(app, { agent, mesh: { /* … */ } });
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. 
{
  type: 'schedule',
  cron: '0 9 * * MON-FRI',
  prompt: 'Email the ops team the overnight order summary.',
}
Supported syntax: *, single values, comma lists (0,15,30,45), ranges (9-17), steps (*/15), weekday names (MON–SUN). 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). 
agent.add_triggers([
  {
    type: 'emit',
    event: 'order_cancelled',
    prompt: 'Order {{order_id}} was cancelled; issue the refund and notify the customer.',
  },
]);

const handle = await attach(app, { agent, mesh: { /* … */ } });

// Somewhere else in the service:
app.post('/orders/:id/cancel', async (req, res) => {
  await db.orders.cancel(req.params.id);
  handle.emit('order_cancelled', { order_id: req.params.id });
  res.sendStatus(204);
});
Use ask when you want the trigger’s result back (rejects after 30 s): 
const summary = await handle.ask('order_cancelled', { order_id });

​
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: 
import { RemoteAgent } from '@svantic/sdk';

agent.on_trigger = async (ctx) => {
  if (ctx.trigger.event === 'order_cancelled') {
    const self = await RemoteAgent.connect(agent.public_url);
    return self.invoke_capability('issue_refund', {
      order_id: ctx.payload.order_id,
    });
  }
};
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