Trigger
A trigger is a document typed hm://hyper.media/trigger, under an app or an agent, that says when to act and what to do, and the server that runs its host fires it.

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

type

hm://hyper.media/trigger

name

the trigger's name

summary

what it is for

source

when it fires: activity conditions, a schedule, a webhook, or a run finishing, stored as nested attributes. See sources

tool

optionally the hm:// URL of one of its host's tools to call

input

optionally the input template for that tool, as nested attributes

enabled

false turns it off

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 ~/triggers/<name>, or use the signed API

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

onFailure can start a session instead

See also

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime