Triggers
Choose the right trigger model for how work should enter an agent and what trust boundary that implies.
Triggers define how an agent starts. Good trigger design is mostly about intentional ingress: who or what can start work, how often, and with what payload shape.
Common trigger types
Manual
Use manual triggers when a person or internal workflow explicitly starts the agent.
If a manual trigger expects structured input, declare manualInput in defineAgent(). That same
literal contract drives the GUI form and the API payload validator, so the code shape and the
manual-run experience stay in sync.
Manual input fields are optional by default. Use required: true on a field when the operator must
provide it before the run can start.
When the operator should choose one mode from a short approved list, prefer a manualInput.select
field over a freeform string. This is the right fit for demo toggles such as block vs redact.
Cron
Use cron triggers for recurring review, sync, or monitoring jobs where timing is the key input.
Webhook
Use webhooks when external systems need to notify the platform about an event.
Trigger design guidance
- Pick the narrowest trigger that matches the business event.
- Make payload expectations explicit.
- Treat externally initiated triggers as trust boundaries.
- Keep high-impact actions behind additional checks or approvals.