STACK
MENU
DOCS / THE ACCOUNT / WAKE-UPS

Wake-ups

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.

Before you start

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.

Wake on an event

prompt
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:

typescript
await stack.wakes.createRule({
  name: 'Mail from Anna',
  source: 'email',
  filters: { from: ['anna@example.com'] },
  task: 'Read and answer the new email.',
}, 'agt_123');
bash
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."
  • Mail, texts, Telegram messages, voicemail, payments and post need a rule before they wake anyone.
  • A ringing call, the end of a call, the start and the end of a meeting, a schedule, a calendar event, a hand-off from another of your agents and a decision the agent waited for wake it without a rule.
  • filters.from takes addresses, @domain for a whole domain, phone numbers, or a Telegram sender as telegram:<username>. filters.min_amount_cents is for payments.
  • task is your own text. Nothing the sender wrote is ever part of it. Without one, the agent gets a fixed line such as "New email."
  • Leave the agent id out to set a rule for every agent of the account.

Wake on a schedule

typescript
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.

How the wake reaches the agent

A wake is tried in this order, which you can change with delivery:

  • A notification on the agent's open MCP session.
  • A signed POST to the agent's webhook, when one is set.
  • The agent's queue, always. A wake is never lost because nothing was listening.

Set a webhook, and STACK returns its signing secret once:

bash
npx @getstackrun/cli wake settings set agt_123 --webhook-url https://agent.example.com/wake

Check each wake your server receives before acting on it:

typescript
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.task
  • The address must be https on a public host, with no query and no fragment.
  • A failed delivery is retried up to 8 times, then the queue alone holds the wake.
  • wake rotate-secret gives a new secret. The old one keeps working for 24 hours.
  • wake test-webhook sends a test wake to the address.

The 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.

Work through the queue

typescript
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.

Quiet hours and limits

bash
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 3600
  • Quiet hours hold wakes until they end, or drop them, as quiet_mode says.
  • There is no limit on wakes unless you set one. Past your limit, events are dropped and counted.
  • There is no limit on the number of rules or schedules.
  • Events that arrive close together become one wake that lists them all.
  • --disable switches wake-ups off for the agent.

What counts as an action

Each 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.

When it is refused

  • 400 WAKE_WEBHOOK_ADDRESS_REFUSED - the webhook address is not https on a public host, or carries a query or a fragment.
  • 400 VALIDATION_ERROR - a cron line, time zone or clock time is wrong.
  • 403 on a settings, rule or schedule call - an agent called it. These are the owner's.
  • With controls on, each wake of an agent with an account is asked of your policy or your own server as wake.deliver. A refused wake is not delivered.

Reference

Every field is on Wake-ups, Calendar and Meetings. Every tool is in the tool reference.

Wake-ups | Docs