How you decide what starts an agent, how the wake reaches it, and how the agent works through its queue. What wake-ups are and what they cost is on Services.
Every agent has wake-ups, with or without an account. Rules, schedules, settings and the webhook are set by the owner or an admin. An agent cannot change its own.
When email from anna@example.com arrives, wake the assistant to read and answer it.The client calls stack_set_wake_rule. From code or the terminal:
await stack.wakes.createRule({
name: 'Mail from Anna',
source: 'email',
filters: { from: ['anna@example.com'] },
task: 'Read and answer the new email.',
}, 'agt_123');npx @getstackrun/cli wake rule-add agt_123 --name "Mail from Anna" --source email \
--from anna@example.com --task "Read and answer the new email."await stack.wakes.createSchedule('agt_123', {
name: 'Morning',
cron: '0 9 * * 1-5',
time_zone: 'Europe/Stockholm',
task: 'Check the open invoices.',
});The tool is stack_set_wake_schedule. cron takes five fields, or @hourly, @daily, @weekly or @monthly. A schedule fires at most every 5 minutes.
A wake is tried in this order, which you can change with delivery:
Set a webhook, and STACK returns its signing secret once:
npx @getstackrun/cli wake settings set agt_123 --webhook-url https://agent.example.com/wakeCheck each wake your server receives before acting on it:
import { verifyWakeWebhook } from '@getstackrun/sdk';
const result = verifyWakeWebhook({ headers: request.headers, body: rawBody, secret });
if (!result.ok) return reply.status(400).send(result.reason);
// result.wake.wake_id, result.wake.source, result.wake.taskThe secret is shown once and cannot be read back. It is never returned to a chat sign-in: set the webhook from the terminal or with an API key.
const queue = await stack.wakes.list('agt_123', { status: 'open' }, { passportToken });
for (const wake of queue.wakes) {
// do the task, then:
await stack.wakes.acknowledge('agt_123', wake.id, { passportToken });
}The tools are stack_list_wakes, stack_get_wake and stack_acknowledge_wake. open is the queue, oldest first. A delivered wake nobody acknowledges expires after 30 days.
npx @getstackrun/cli wake settings set agt_123 --time-zone Europe/Stockholm \
--quiet 22:00-07:00 --quiet-mode hold --rate-limit 30 --rate-window 3600Each wake delivered is one action. Setting rules, schedules and settings, reading the queue and acknowledging are free. A wake that is refused is not charged.
Every field is on Wake-ups, Calendar and Meetings. Every tool is in the tool reference.