A trigger, with a prompt or a prompt_file. agent.trigger_set and agent.trigger_remove return it with its name. A scheduled trigger has every. A one-off trigger has at, runs once, and is then removed. Add timezone for cron expressions and times outside UTC. A feed trigger has feed, with one or more RSS or Atom feeds. A webhook trigger has webhook instead of every. Set its secret as ${NAME} and verify to shared or standard. It receives requests at POST /v1/hooks/{agent}/{trigger}. The defaults are overlap settle (queue for at and webhooks), missed run_once and jitter 0.
| Property |
Type |
Description |
name? |
string |
The trigger name, taken from the path. |
every? |
string |
A cron expression, or an interval such as 30m. |
at? |
string |
Use instead of every. A single time to run once, as 2026-11-17T09:00, read in timezone, or with an offset, as 2026-11-17T17:00:00Z, and no timezone. The trigger is removed after it runs. Setting a time that has passed is refused. |
timezone? |
string |
The IANA time zone for a cron expression in every, or for at, such as Europe/Berlin. Defaults to Etc/UTC. Not used with an interval. |
next_at? |
string |
When the trigger runs next, in its time zone. agent.trigger_set returns it. A webhook, or an at that has run, has none. |
prompt? |
string |
The prompt sent to the agent on each run. |
prompt_file? |
string |
Use instead of prompt. A file in the agent's workspace. Each run asks the agent to read the file and follow its instructions. The agent's tools must include files. |
overlap? |
"skip" | "queue" | "settle" |
What happens if the agent is busy when the trigger fires. skip skips the run. queue runs it after the current turn. settle cancels a turn that is waiting for an approval and runs. If the turn isn't waiting for an approval, settle skips the run. |
missed? |
"skip" | "run_once" |
What to do about runs missed while the server was down. |
jitter? |
number |
A random delay of up to this many seconds before each run. |
feed? |
string | string[] |
An RSS or Atom feed URL, or a list of them. The agent runs only when a feed has new entries, which are added below the prompt. The first check records the current entries without running the agent. |
webhook? |
object |
Use instead of every. An external service sends requests to the trigger. Each request runs the agent once. |
webhook.secret |
string |
The shared secret, as a reference, for example ${NAME}. |
webhook.verify? |
"shared" | "standard" |
How requests are verified. With shared, the request sends the secret as a bearer token or as the last path segment of the URL. With standard, the request is signed as the Standard Webhooks spec describes. Defaults to shared. |