Skip to main content

Triggers & Scheduling

Not every agent run starts with a user typing. Triggers and scheduling let the harness start runs on a cron schedule, in response to an event, or as detached background work — and re-engage a paused run when the thing it was waiting for happens.

An agent that only runs when summoned is a tool. An agent that wakes on a schedule, reacts to a webhook, or resumes itself when a long job finishes is infrastructure. Triggering is what moves an agent from interactive to autonomous.

Structure​

One dispatcher starts runs from any source — schedule, event, resume, or on-demand — and a run can schedule its own future wakeup, closing the autonomy loop.

How It Works​

  1. Define trigger sources — cron schedules for recurring work, event/webhook handlers for reactive work, and explicit wakeups for paused, durable runs resuming.
  2. Dispatch uniformly — every trigger funnels into the same run dispatcher, so scheduled and on-demand runs share one execution path.
  3. Run in the background — detach long or scheduled runs from any interactive session; they execute independently and report on completion.
  4. Self-schedule — a run can set its own next wakeup ("check the deploy in 5 minutes"), pacing recurring polling without a human in the loop.
  5. Coordinate, don't duplicate — guard against overlapping fires of the same scheduled job (locking, dedup) so two copies don't run at once.

Key Characteristics​

  • Many sources, one path — schedule, event, resume, and manual all dispatch the same way, which keeps behavior and observability consistent.
  • Background runs need their own session — detached work persists state and reports asynchronously rather than blocking a caller.
  • Self-scheduling enables polling without humans — a run that re-arms its own wakeup can watch external state on a sensible cadence.
  • Idempotent triggers prevent doubles — a webhook delivered twice or an overlapping cron fire must not run the work twice.
  • Wakeups close the durability loop — pausing for an event and being woken by it is what makes long-horizon, event-driven agents possible. Scheduled and background runs — long, unattended, spanning deploys — are exactly where Temporal-style durable resume earns its keep.

Pitfalls​

  • Overlapping schedules — a job that runs longer than its interval, with no guard, stacks copies until something falls over.
  • Polling too aggressively — waking every few seconds to check slow-changing state burns budget; pace wakeups to how fast the state actually changes.
  • Reactive infinite loops — an agent that triggers an event it then reacts to. Add dedup and circuit breakers.