> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Agent triggers

> Guild triggers run agents automatically from events in connected services, on recurring schedules, or via API calls. Create, rename, pause, and inspect them.

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.

<iframe src="https://www.youtube.com/embed/DsUDLPRKNsY" title="YouTube video player" frameborder="0" className="w-full aspect-video rounded-xl" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Trigger types

<CardGroup cols={3}>
  <Card title="Event" icon="bolt" href="/platform/event-triggers">
    Fires when an event occurs in a connected service, such as a new Slack mention or a GitHub pull request.
  </Card>

  <Card title="Schedule" icon="calendar-days" href="/platform/schedule-triggers">
    Fires on a recurring schedule: hourly, daily, weekly, or monthly.
  </Card>

  <Card title="API" icon="code" href="/platform/api-triggers">
    Fires on demand when an authenticated HTTP request is made to the workspace session endpoint.
  </Card>
</CardGroup>

## Create a trigger

<Steps>
  <Step title="Open your workspace">
    Go to [app.guild.ai](https://app.guild.ai) and open the workspace where the agent is installed.
  </Step>

  <Step title="Go to Triggers">
    In the workspace's left nav, click **Triggers** under **Run**, then click **Add Trigger**.
  </Step>

  <Step title="Choose a type">
    Select **Event**, **Scheduled**, or **API**, then configure the trigger. See [Event triggers](/platform/event-triggers), [Schedule triggers](/platform/schedule-triggers), or [API triggers](/platform/api-triggers) for type-specific setup and examples.
  </Step>

  <Step title="Select an agent">
    Choose the agent the trigger will run when it fires.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Manage triggers

These commands work on triggers of any type.

### Activate and deactivate

Deactivate a trigger to pause it without deleting it.

```bash theme={null}
guild trigger deactivate <trigger-id>
guild trigger activate <trigger-id>
```

### 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:

```bash theme={null}
guild trigger update <trigger-id> --name "Nightly report"
```

### List and inspect

```bash theme={null}
# List all triggers in the workspace
guild trigger list

# Get details for a specific trigger
guild trigger get <trigger-id>

# List sessions spawned by a trigger
guild trigger sessions <trigger-id>
```

## 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](/platform/workspace-variables) 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](/platform/sessions#event-log) alongside the task's other events. This applies to every trigger type.

## Related pages

* [`guild trigger`](/cli/commands/trigger) for every trigger subcommand and flag
* [Identity mapping](/platform/identity-mapping) so event-started runs act as the member who caused the event
* [Post a daily digest of untriaged GitHub issues to Slack](/platform/recipes/daily-issue-digest) for a schedule trigger built end to end
* [Review every new GitHub pull request](/platform/recipes/github-pull-request-review) for an event trigger built end to end
* [Post release notes to Slack from CI](/platform/recipes/ci-release-notes) for an API trigger built end to end