Trigger an agent from events
Kick off an agent automatically when something happens in a connected app.
Advanced · ~15 min · Prerequisites: a connected app
Building and editing agents is admin-only. Members can run and observe agents, but only admins can create or change them.
What you'll do
Wire a published agent to an event in one of your connected apps so it runs automatically whenever that event fires — no schedule, no manual prompt.
Pick a trigger
Open the agent at /admin/agents/<slug>/edit and go to the Triggers section. Click + Add trigger to browse the available event sources. Triggers come from your connected apps — Gmail, Slack, GitHub, and others — so only apps your org has already connected appear here. If the app you need isn't listed, connect it first; see Connecting apps.
Each trigger is a specific event type within an app:
- Gmail: new email received, email labeled, email marked important
- Slack: message posted to a channel, reaction added, direct message received
- GitHub: pull request opened, issue created, review requested
Choose the event that matches the moment you want the agent to respond. For the full list of supported trigger types and their payloads, see Triggers.
Triggers fire for every matching event across the connected app — not just events from a specific user. Use filter conditions to narrow the scope.
Bind it to the agent
After picking a trigger event, configure any filter conditions to narrow which events actually fire the agent. For example:
- Gmail "new email received" → filter to
from: @yourbiglead.comorsubject contains: urgent - Slack "message posted" → filter to a specific channel or messages that @mention the agent
- GitHub "pull request opened" → filter to a specific repository or label
Add a trigger prompt — the message the agent receives when the event fires. Use template variables to inject live event data into the prompt:
<event.subject>— email subject line<event.sender>— who triggered the event<event.body>— event content or message body
A good trigger prompt is direct and includes the event data the agent needs: "A new support email arrived from <event.sender> with subject '<event.subject>'. Triage it: categorize by issue type, assess urgency, and draft a reply."
Define the response
The agent runs its full instructions plus the trigger prompt on every matching event. Because there is no human in the loop, the instructions and prompt together must be complete enough for the agent to act correctly without follow-up.
Think through the failure modes before you publish:
- What happens if the event data is incomplete or malformed?
- Does the agent have the right tools to take the action (create a ticket, post a reply, update a record)?
- Is the output going somewhere the right person will see it?
Set the output destination the same way you would for a scheduled run — inbox notification, channel post, or a document. For high-volume triggers, a channel post or document append tends to be more manageable than individual inbox notifications.
Test and manage
Use the test panel in the editor to simulate a trigger event before the integration goes live. Paste a sample event payload and confirm the agent's response matches what you expect. Test panel runs are isolated — they don't fire real actions in connected apps.
Once you're satisfied, save and ensure the agent is published. The trigger becomes active immediately.
To pause a trigger without deleting it, toggle the Active switch next to the trigger entry and save. To remove a trigger entirely, click the delete icon on the trigger row. The agent itself stays published and available for manual chat — only the automatic trigger is removed.
To edit filter conditions or the trigger prompt, open the trigger row, make changes, and save. Changes take effect on the next event that fires.