A trigger is a rule that makes something happen when nobody asks for it. For example, a trigger can call a fetch-news tool every hour, or start a session with an agent each time someone mentions it in a comment.
A trigger can fire on a schedule, when a comment or a mention appears, when a webhook is delivered, or when a run finishes. It is a document whose metadata declares type: hm://hyper.media/trigger. Like a tool, it lives directly under an app or an agent, called its host. The host lists the trigger with a card embed.
This page says what a trigger is and how the document relates to the server that fires it. An agent can also keep triggers that are not documents. They follow different rules, and the last section covers them. The exact shapes are in the trigger reference.
What a trigger is made of
Attribute | Value |
|---|---|
|
|
| the trigger's name |
| what it is for |
| when it fires: activity conditions, a schedule, a webhook, or a run finishing, stored as nested attributes. See sources |
| optionally the hm:// URL of one of its host's tools to call |
| optionally the input template for that tool, as nested attributes |
|
|
The document's body is used too. For a trigger that starts an agent session, the body is the session's first message.
What it does when it fires
Each time a trigger goes off is a firing. A firing does one of two things.
Call a tool of its host:
input is a template. The server replaces the string values "$event" and "$event.<path>" with data from the event. A webhook's posted JSON is "$event.payload".
Without input, the tool gets the whole event.
An app's trigger must call a tool.
The server records the call like any other run of the tool, as made by the trigger's author. The author is the account that signed the trigger's latest version. The space accepted that version, so the author is a writer of the host.
The call record is as public as any other call record. See tool.
Start a session with an agent. Only an agent's trigger can do this. Leave out tool, and the trigger's body is the session's first message.
A trigger can only call a tool of its own host.
The document and the server
The document is the trigger. The server that runs the trigger's host fires it. That server is the app environment:
An app's triggers fire while the app runs on its server.
An agent's triggers fire while the agent is mounted on its server.
The server reads its hosts' trigger documents every minute. It also reads them at once when a client asks for a host's triggers, or when an agent on that server writes one.
For each document the server keeps one row in its trigger table. The row holds the source, the action and the document version it was read from. The server matches sources and records firings against that row. An app's trigger rows are kept under the account that ran the app.
The row is a copy that the server needs in order to work. You never edit a trigger there:
To change a trigger, publish a new version of its document. The server's own trigger actions refuse a trigger that is a document, and name the document instead.
A trigger stops firing when its card leaves its host or its document is deleted. This takes about a minute. If the trigger changed in the last 10 minutes, it can take up to 10 minutes. A delete that an agent on that server makes with its write verb stops the trigger at once.
When an app stops, its triggers stop with it.
An edit that makes a trigger invalid stops it, so an old version never keeps firing. The server reports the trigger with the reason.
The server holds what must not be public: a webhook trigger's secret, and the history of firings.
ListHostTriggers {hostId} returns a host's triggers as its server holds them. Each one comes with its recent firings. The answer also lists the triggers the server could not use, with the reason. A writer of the host's space also gets each webhook trigger's secret. A firing of an app's trigger names the tool call it made. The signed API for triggers has the shapes.
Triggers kept only on the server
An agent can also hold triggers that exist only as rows on its server, with no document. These pages call them triggers stored on the server. An app has none.
Such a trigger joins a source (what happens) to a continuation (what to do). It can do things a trigger document cannot: run a workflow script, wake a parked run, call a builtin or MCP tool, or start a session with its own system prompt. The trigger reference lists every source and continuation. These triggers live at ~/triggers/<name> in the agent's Space, and the agent creates, edits, enables, and disables its own triggers there.
A trigger document can express two actions: call a tool of the host, and start a plain session. So the two forms relate like this:
If a document can express a stored trigger, the server publishes it as a trigger document under the agent's document. The agent's primary account signs it. This needs the agent to have write access there, which you give from the agent's People tab. Until then the server keeps trying. The trigger keeps its id, webhook URL, firings and claims.
If a document cannot express a trigger's action, the trigger stays on the server only. That is a workflow script, a wake, a call to a builtin or MCP tool, or a session with its own system prompt or narrowed tools.
~/triggers/ lists all of an agent's triggers, of both forms. It names the document of each trigger that has one.
Some rules differ between the two forms:
Rule | Trigger document | Trigger stored on the server |
|---|---|---|
How you edit it | publish a new version of the document | write |
Change to or from a webhook source | allowed; the server makes a new secret each time the source becomes a webhook | refused; make a new trigger |
What happens when a tool call fails | the firing is recorded as failed |
|
See also
Trigger reference for sources, continuations, the stored form, monitors and the actions that edit triggers.
Firing for how an activation is recorded exactly once.
Webhooks for delivering events from outside.
Building an app for making a trigger in the desktop app or as an agent.
Security for what agent-managed triggers mean for the threat model.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime