Skip to main content
A trigger runs an agent automatically — either when an event occurs in an external service, on a recurring schedule, or on demand via an API request.

​
Trigger types

Event

Fires when an event occurs in a connected service, such as a new Slack mention or a GitHub pull request.

Schedule

Fires on a recurring schedule: hourly, daily, weekly, or monthly.

API

Fires on demand when an authenticated HTTP request is made to the workspace session endpoint.

​
Create a trigger

1

Open your workspace

Go to app.guild.ai and open the workspace where the agent is installed.
2

Go to Triggers

In the workspace’s left nav, click Triggers under Run, then click Add Trigger.
3

Choose a type

Select Event, Scheduled, or API, then configure the trigger. See Event triggers, Schedule triggers, or API triggers for type-specific setup and examples.
4

Select an agent

Choose the agent the trigger will run when it fires.
5

Name the trigger

Enter a Name, such as Nightly report. The name is required, up to 255 characters, and labels the trigger in the workspace’s Triggers list.

​
Manage triggers

These commands work on triggers of any type.

​
Activate and deactivate

Deactivate a trigger to pause it without deleting it.

​
Rename

In the Triggers list, open the trigger’s edit dialog and change Name. The name can’t be empty. From the CLI, rename a trigger of any type, including an API trigger:

​
List and inspect

​
Dispatch failures

When Guild cannot dispatch a triggered run to the agent, it records the failure and moves the task to an error state, rather than leaving it pending indefinitely. Dispatch fails when:
  • The event payload or the trigger’s custom agent input is invalid.
  • The input does not validate against the agent’s input schema.
  • A workspace variable the input references has no value.
  • The agent version has been deleted or is unreadable (event triggers).
The failure is recorded as a system_error event on the task, carrying the underlying message, so it appears in the session’s event log alongside the task’s other events. This applies to every trigger type.
Last modified on October 15, 2026