- Polling triggers look for events themselves, such as by checking an inbox every minute.
- Push triggers receive events from a provider’s webhook, such as Slack’s.
Declare a polling trigger
Each trigger has adescription, a JSON Schema config that requesters fill in, and an onScheduleActive hook (on_schedule_active in Python) that sets up the events for one schedule. A polling trigger calls fire() for each event it finds, and returns a stop function that stops looking for events:
task.event. create() advertises each trigger’s description and config schema, and the handle that create() returns keeps the hook. If you later connect with the top-level connect(), pass the same skills so your process runs the hooks.
Schedule a trigger
Requesters schedule a trigger by name, with its config, instead of a cron. Every run carries the event that started it:find() and the find_agents tool list each skill’s triggers with their config schemas.
When the hook runs
The hook runs once the schedule becomes active, and again in each of these cases:- Each time the executor connects, for every trigger schedule still active.
- In another process of the same agent, when the process that was watching the schedule leaves.
credentials(connection) returns an access token, account(connection) returns the connected account, and connectionFetch(connection) sends requests through a secret connection. The SDK calls stop once the schedule ends or the process stops watching the schedule. After that, fire() does nothing.
Push triggers
With a push trigger, the provider sends events to your webhook instead of your hook firing them. The hook subscribes the schedule to event keys, which are strings you choose to label events, such asslack:T1:message:C9. A hook can return up to 20 keys, and each key can be up to 256 characters long. The keys it returns replace any the schedule had before.
When your webhook receives an event, call dispatch() on the executor with the event’s keys. You can call it from any process where the executor is connected. The network then starts one run for each active schedule subscribed to any of those keys. If the same event id is dispatched again, schedules that already ran for it don’t run again:
stop function that ends the renewals:
Stop reasons
stop receives the reason the process stopped watching the schedule, so it can undo only what no longer applies:
For example, this hook registers a webhook named after its schedule. Registering the webhook again in each process is harmless, and the hook deletes the webhook only once the schedule has ended. Here,
statuspage is a secretConnection() the skill declares:
stop runs, unless the schedule ended because its human revoked one of them. If stop takes longer than 30 seconds, the SDK reports the delay to your error handler and releases the schedule’s credentials.
Receive webhooks with an event source
An event source turns a provider’s webhook requests into events, and verifies each request itself. Pass one toreceiveEvents() (receive_events() in Python) along with the request. Providers sign the raw request body, so pass the body exactly as it arrived.
receiveEvents() dispatches each event the source reads, and returns the response to send back to the provider. If dispatching fails, the response is still returned and the failure goes to your error handler. receiveEvents() also ends the grants of any account that the provider reports as revoked, such as a workspace that uninstalled your app.
To support a new provider, implement an event source’s receive() method:
Reliability
- Duplicate events. Firing an event with an id that already started a run doesn’t start another run, so a poll can safely fire events it has seen before.
- Dropped connections. A dropped connection doesn’t stop a trigger. Events fired or dispatched while the agent is disconnected are sent once it reconnects. If an event waited more than an hour,
fire()throws aTriggerFailedErroranddispatch()throws aDispatchFailedError, instead of starting a stale run. - Event size. An event’s
summarytells the requester what happened, and can be up to 1,000 characters long. The event’s optionaldatais a JSON object of up to 64 KB that carries what the run needs, such as a message’s thread. Only the executor receivesdata.
Budgets and billing
A trigger can fire any number of times, so a schedule on a priced skill can set abudget that caps how many runs it has, or how much it spends, in each period. An event that would go over the budget is skipped, and the schedule carries on.
If billing is temporarily unavailable when an event fires, the network keeps retrying the charge for up to an hour. If billing doesn’t recover, the executor’s error handler receives a TriggerFailedError with the event id. The executor can then fire that event again.