Skip to main content
Run a tool on a schedule through the backend. The runtime runs a registered tool periodically. A schedule names the tool, its arguments, and a cadence; a worker backend fires it on time. Scheduled runs execute on the backend, so a backend plugin must be configured for schedules to run.

​
Configure a backend

A schedule runs on the worker backend, not in the request path. Register a backend plugin under backend_module in the manifest and start its worker runtime:
manifest.yml
See Backends for where tools run.

​
Attach the schedule extension

The friendly tai schedules add form fires the tool’s <tool>_schedule_task branch — the backend’s schedule_task extension. Naming the backend under backend_module registers that extension, but it is never attached to a tool on its own: name it in the tool’s per-tool extensions map so the branch exists.
manifest.yml
Without the extension the tool has no report_schedule_task branch, and tai schedules add report --schedule-kw cron=... answers a 404 — the cadence has no vehicle to run on.

​
Add a schedule

Name the tool to run and its cadence. Pass tool arguments with --tool-kw key=value (or --tool-kwargs as JSON), and the cadence with --schedule-kw (or --schedule-kwargs).
Give the cadence one of two ways:
  • cron — a crontab string, as above ('0 9 * * *' fires at 09:00 every day).
  • Structured fields — minute, hour, day_of_month, month_of_year, and day_of_week set the crontab parts individually, e.g. --schedule-kw hour=9 --schedule-kw minute=0.
Passing both cron and a structured field at once is an error. Either form is translated onto the tool’s schedule_task branch for you.

​
The expert form

To hand the cadence to the backend untouched, pass backend_schedule (the backend’s own schedule spec) and optionally backend_schedule_name through --schedule-kw, or name the <tool>_schedule_task branch as the tool directly. Both skip the translation above and dispatch the backend’s scheduling parameters as given.

​
Inspect and remove

1

List schedules

2

Check the server clock

Cron cadences resolve against the server’s clock — read it to reason about when a job fires.
3

Delete a schedule

A schedule and a webhook binding are the two ways a tool fires without a client call. To fire a tool on an inbound event instead, see Fire a tool from a webhook.

​
See also