Triggers & Inputs
How a Trelium agent knows there is work to do and what it receives when a job starts. Covers event and schedule triggers, the kinds of input an agent can read, and what happens when an input is unclear or incomplete.
Every run of a Trelium agent starts with a trigger. The trigger tells the agent that there is work to do, and it hands over the item to work on. Getting this first stage right keeps the rest of the job simple, because the agent only starts when something real has arrived.
What is a trigger?
A trigger is the event or schedule that starts a run. A run is one pass through the workflow, and it can handle a single piece of work, such as one customer email, or several items in one pass. How the agent picks what to work on, and how it ignores unrelated messages, is set in that workflow. The trigger is set when the agent is built, and the agent acts only on the kind of work it was set up for.
Common kinds of trigger include:
- An event. Something happens in a tool your team already uses, such as a customer email arriving in an inbox, someone posting a request in a Slack channel, or a webhook or other integration event the workflow listens for.
- A schedule. The agent starts at set times, such as a check every morning at 8. A scheduled job can also pick up a file that lands on a cadence your team agreed, rather than needing a separate "file just arrived" trigger.
- A manual start. Someone starts or wakes a job from Trelium when they want that work to run now.
Events suit work that arrives unpredictably, like purchase orders. Schedules suit work that needs a regular look, like checking for overdue invoices or building a morning report. The exact triggers available for your tools are set during setup; treat the list above as examples, not a full catalog.
The trigger as it appears at the top of the PO entry agent's Flow: an event trigger on a Gmail inbox, limited to emails whose subject starts with PO.
What is an input?
The input is the item the trigger hands to the agent. It is what the agent reads and works on for that run. Inputs can be:
- An email, with or without attachments
- A PDF, such as a purchase order or a supplier invoice
- A spreadsheet
- A form
- A request, such as a message in a Slack thread
Work like this rarely arrives in one tidy format. A purchase order might come in as a PDF one day, a spreadsheet the next, and a plain email after that. The agent reads each one and works out the same things every time: who it is from, which order or record it refers to, and what is being asked.
A scheduled run may have no incoming item to read. Instead, it can start from the systems it checks, such as a list of open invoices.
From trigger to first step
The trigger is stage 1 of the eight stages. Once the agent has its input, it moves on to gathering context. It looks up the customer, finds the order the email refers to, and checks current stock, prices, or status in your systems at that moment. That way it works from today's numbers, not an old copy.
flowchart LR A["Email arrives or schedule fires"] --> B["1. Trigger input handed over"] --> C["2. Gather context"] --> D["Rest of the workflow"]
Example: a request in a Slack channel
A sales team wants to know whether a company is worth pursuing. Someone posts the company's name in a team Slack channel. That post is the trigger, and the message is the input. The agent acts only on requests like this one.
The agent first reads the message to work out which company, or companies, it names. If the name matches several companies or none, it asks in the thread instead of guessing, and the run carries on from the person's answer. The same example is walked through stage by stage in How Trelium Works.
More examples from these docs
Each of these agents is shown with screenshots elsewhere in the docs.
| Agent | Trigger | Where it is shown |
|---|---|---|
| PO entry | A new email in Gmail whose subject starts with "PO" | Purchase Order Entry |
| Proof replies | A new email with "proof" in the subject | Choosing a Workflow |
| Inquiry replies | An email in the company Gmail inbox asking about a team onboarding session | Your First Workflow |
| Company check | A request posted in a team Slack channel | How Trelium Works |
The first two show a common way to keep an agent on its own job: the trigger looks for a word in the subject line, so other mail in the same inbox does not start a run. Filters like that are workflow-specific. An agent can also keep listening after it decides a message is not for it.
When an input is unclear or incomplete
Not every input is clean. A customer might forget an order number, attach the wrong file, or write a request that could mean two things. In these cases the agent does not guess. It either asks for the missing detail or passes the run to a person, depending on how the workflow is set up. See Human in the Loop and Validation & Exceptions.
Choosing a good trigger
A few questions help when you decide how a job should start.
- How does the work arrive today? If it lands in an inbox or a channel, an event trigger on that inbox or channel is usually the natural fit.
- Does it need to happen right away? If a customer is waiting on an answer, use an event. If a daily summary is enough, use a schedule.
- Should every message start a run? If the inbox also receives mail that is not part of this job, set filters in the workflow so the agent acts only on the kind of request it was built for, and ignores the rest.
Words used on this page
- Trigger: the event or schedule that starts a run.
- Input: the item the trigger hands to the agent, such as an email, attachment, form, or request.
- Run: one pass through the workflow, covering one or more pieces of work.
- Workflow: the written procedure an agent follows for one kind of job.
Where to go next
Human in the Loop
How your team stays in charge of Trelium agents. Covers what agents do alone, what they prepare for approval, what stays manual, when a run goes to a person, and how to give agents more freedom over time.
Logs & Audit Trails
How the Activity log records what an agent did, how to use it to review a piece of work, and what it does not cover.