> For the complete documentation index, see [llms.txt](https://docs.cleric.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cleric.ai/setup/agents-and-triggers.md).

# Configuring Automations

Configure the workflows Cleric runs and how alerts are routed to them

An **agent** is a named workflow with custom instructions that Cleric runs against an issue. A **trigger** is a rule that runs an agent automatically when a matching event fires. Cleric supports two trigger types: **Bot message**, which fires when a bot message posted in a Slack channel matches the trigger's keywords, and **Scheduled**, which fires on a recurring cron schedule.

{% hint style="info" %}
**Existing customers:** Triggers replace the prior "alert responses" configuration. Existing keyword routing was migrated automatically to triggers that point at the built-in `investigate` agent. No action is required to preserve previous behavior.
{% endhint %}

## Agents

### Built-in

The built-in `investigate` agent runs Cleric's deep root-cause analysis, exploring widely, forming hypotheses, and prioritizing accuracy over speed. It runs by default on alert-driven issues. On user-initiated issues, it runs when the message includes `!investigate` or natural-language investigation phrasing such as "investigate", "diagnose", "debug", "root cause", "look into", or "dig into".

The `investigate` agent cannot be edited or deleted.

### Custom agents

A custom agent has two fields:

* **Name**: lowercase letters, numbers, and hyphens (e.g. `checkout-incident`, `db-failover`). Must start and end with an alphanumeric character, max 50 characters. Cannot collide with reserved names (e.g. `investigate`).
* **Instructions**: free-text prompt that runs alongside Cleric's instructions when this agent fires.

Custom agents let you apply Cleric to workflows beyond the default investigation. Use them for a lighter-weight response to events like deployment failures or to run a tailored workflow outside of a deep investigation.

#### Example: Assess a pipeline failure

**Name**: `pipeline`

**Instructions**:

```
Your role is to determine why the pipeline job failed.

1. Retrieve the link to the failing job and check the GitHub Actions workflow logs.
2. Review the corresponding commit.
3. Determine: is the failing check a result of the commit, a previous commit (i.e. the same job failed in the previous workflow as well), or a transient failure?

List your recommendation for how to proceed.
```

#### Example: Monitor a feature rollout

**Name**: `monitor`

**Instructions**:

```
Review the PR or commit that triggered the given GitHub Actions pipeline so you understand the context.

Check the status of the pipeline. If it's still in progress, schedule a follow-up to check again in 5 minutes.

If the pipeline completed successfully and non-trivial changes were rolled out, schedule a follow-up in 1-2 hours to verify the changes are working as expected.
```

### Running an agent

Agents run in two ways:

**From a trigger (automatic).** When a **Bot message** trigger matches an incoming bot message, or when a **Scheduled** trigger's time elapses, Cleric runs the trigger's agent. See [Triggers](#triggers) below.

**On-demand with `!agent-name`.** In any Slack thread or web chat, prefix your message with `!` followed by the agent's name to run that agent on the issue:

```
@Cleric !monitor the rollout of PR#1234.
```

`!agent-name` works in a new chat or as a follow-up in an existing thread.

### Managing agents

{% stepper %}
{% step %}

#### Open the Agents page

In the Cleric web app, open **Automation > Agents** in the sidebar.
{% endstep %}

{% step %}

#### Create a new agent

Click **New agent**. Give it a name and write instructions. The form validates the name format and rejects names already taken by another agent.
{% endstep %}

{% step %}

#### Save

Click **Save**. The agent is now available to run on demand via `!agent-name` and to attach to a trigger. Use the **Run agent** button on the agent's detail page to launch a new chat with `!<name>` pre-filled.
{% endstep %}

{% step %}

#### (Optional) Wire a trigger

If you want the agent to run automatically, open the **Triggers** page and add a trigger: a **Bot message** trigger to run on matching bot messages, or a **Scheduled** trigger to run on a recurring schedule.
{% endstep %}
{% endstepper %}

### Limitations

* Built-in agents cannot be edited, renamed, or deleted.
* Custom agent names must be unique.
* Deleting a custom agent also deletes any triggers that route to it.
* Editing an agent's instructions takes effect on its next run. Follow-up messages in an existing thread also pick up the updated instructions.

## Triggers

A trigger runs an agent automatically when a matching event fires. Each trigger has a type that determines the event it listens for:

* **Bot message**: fires when a bot message posted in a Slack channel matches the trigger's keywords. Cleric runs the selected agent and replies in the thread.
* **Scheduled**: fires on a recurring cron schedule. Cleric posts the result to the configured Slack channel.

### How a trigger fires

When a bot posts a message in a channel with one or more **Bot message** triggers:

1. Cleric evaluates triggers in their listed order (top-down) for that channel.
2. For each trigger: if the message matches at least one keyword and doesn't match any of the trigger's exceptions, the trigger fires. The first match wins.
3. Cleric reacts with :eyes: on the message.
4. Cleric runs the trigger's agent on the resulting issue and posts a "Follow my progress" link in the thread.
5. When the agent completes, Cleric posts the result and updates the reaction to :white\_check\_mark: (success) or :warning: (failure).

If no trigger matches, Cleric ignores the message. `@Cleric` mentions are not subject to triggers. They always create an issue regardless of channel configuration (see [Collaborating with Cleric](/usage/collaborating-with-cleric.md)).

If the message matches a recent issue in the same channel, Cleric attaches it to that issue instead of running the agent again. See [How Investigations Work](/usage/how-investigations-work.md#from-alerts).

### Keyword matching

Each trigger requires at least one keyword. The trigger fires when the message text contains any of its keywords. Use `*` to match all bot messages. Exceptions are optional; if the message matches any exception, the trigger does not fire even when a keyword matches. Use exceptions to suppress test alerts, staging environments, or resolution notifications.

Keywords match as **case-insensitive substrings**.

| Keyword     | Matches                                                                              |
| ----------- | ------------------------------------------------------------------------------------ |
| `error`     | Any message containing "error" (e.g., "error occurred", "critical\_error", "errors") |
| `OOMKilled` | Any message containing "oomkilled" (case-insensitive)                                |

`*` is a wildcard that lets you require terms in a specific order:

| Keyword      | Matches                                                                               |
| ------------ | ------------------------------------------------------------------------------------- |
| `*`          | Every bot message in the channel (useful when the channel is high-signal)             |
| `error*rate` | Text where "error" appears before "rate" (e.g., "error\_rate", "error rate exceeded") |
| `pod*crash`  | Text where "pod" appears before "crash" (e.g., "pod xyz crashed", "pod-abc-crash")    |

{% hint style="info" %}
Since keywords already match as substrings, `error` and `*error*` behave the same way. Use wildcards when you need to match multiple terms in a specific order (e.g. `pod*crash`), or to fire on every bot message in a channel (`*`).
{% endhint %}

### Trigger order

Within a channel, triggers evaluate top-down and the **first match wins**. Order matters when the same message could match more than one trigger. This typically happens when a specific trigger and a wildcard (`*`) route to different agents.

When a channel has more than one trigger defined, drag the handle to reorder them. Put more specific triggers above broader ones. Reordering is disabled while any filters are applied so the visible order matches the actual evaluation order.

### Validation

Cleric blocks two types of misconfiguration when you save a trigger:

* **Duplicate**: a trigger already exists in this channel for the selected agent. The dialog links you to the existing one so you can edit it instead.
* **Conflict**: another trigger in this channel matches the same messages and routes them to a different agent. This happens when:
  * Two triggers have the **same keywords** (or both are catch-all) and route to different agents. The first trigger always wins, so the second would never fire.
  * Two non-catch-all triggers **share at least one keyword** and route to different agents. Cleric can't determine which should run when a message matches both.

A catch-all trigger combined with more specific triggers routing to different agents is allowed. Place the specific triggers above the catch-all so they match first, leaving unmatched messages for the catch-all.

### Adding a Bot message trigger

{% stepper %}
{% step %}

#### Open the Triggers page

In the Cleric web app, open **Automation > Triggers** in the sidebar.
{% endstep %}

{% step %}

#### Add Cleric to the channel (if needed)

In Slack, use `/invite @Cleric` to invite Cleric to the channel. Once Cleric is a member, the channel becomes selectable in the trigger dialog.
{% endstep %}

{% step %}

#### Add a trigger

Click **Add trigger**. In the **When** section, keep the **Bot message** type selected, then configure:

* **Channel**: select the Slack channel.
* **And matches keyword(s)**: enter keywords that fire the trigger (comma-separated). Optionally add **Except for** keywords to suppress matches.
* **Then** → **Run agent**: select the agent to run.

The Preview block at the bottom updates as you edit and shows the rule in plain English (e.g., *When a bot posts in #alerts-prod, matching "P0" or "Sev1", except "staging", run the **investigate** agent.*).
{% endstep %}

{% step %}

#### Save

Click **Add trigger**. Validation errors (duplicate or conflict) appear inline with a link to the conflicting trigger. The trigger takes effect immediately.
{% endstep %}

{% step %}

#### (Optional) Order triggers within a channel

If a channel has more than one trigger, drag triggers into the order you want them evaluated. Put specific triggers (e.g. matching a specific keyword) above generic triggers (e.g. catch-all `*`).
{% endstep %}
{% endstepper %}

### Scheduled triggers

A **Scheduled** trigger runs an agent on a recurring schedule and posts the result to a Slack channel. Unlike **Bot message** triggers, Scheduled triggers don't react to channel messages: they fire on the schedule you set, regardless of channel activity.

The trigger dialog offers five repeat presets:

* **Every hour**: fires once per hour, on the minute you set.
* **Every day**: fires daily at the time you set.
* **Every weekday**: fires Monday through Friday at the time you set.
* **Every week**: fires on the days of the week you select, at the time you set.
* **Every month**: fires on the day of the month you select (1-28), at the time you set.

Times use a 24-hour clock (for example, `14:30` is 2:30 PM). The schedule honors the timezone you select and adjusts for daylight saving transitions in that zone. Monthly schedules are capped at day 28 so the trigger fires consistently in every month.

### Adding a Scheduled trigger

{% stepper %}
{% step %}

#### Open the trigger dialog

In the Cleric web app, open **Automation > Triggers** in the sidebar and click **Add trigger**.
{% endstep %}

{% step %}

#### Select the Scheduled type

In the **When** section, switch from **Bot message** to **Scheduled**.
{% endstep %}

{% step %}

#### Set the cadence

Select a **Repeat** preset and the **At** time. For **Every week**, also select the days of the week. For **Every month**, also select the day of the month. Select a **Timezone**.
{% endstep %}

{% step %}

#### Select the agent and destination

Under **Then**, select the **Run agent** to invoke and the **Post results to** Slack channel where Cleric should send the output.
{% endstep %}

{% step %}

#### Save

The **Preview** at the bottom reads the schedule back in plain English (e.g. *Every weekday at 9:00 AM (America/Los\_Angeles), run the **investigate** agent and post to #alerts-prod.*) and shows the next run time. Click **Add trigger**.
{% endstep %}
{% endstepper %}

To edit or delete a Scheduled trigger, click its row on the **Triggers** page.

## On-demand investigations

Triggers control what runs **automatically** on bot messages. They do not affect `@Cleric` mentions or web-app investigations. You can always:

* Mention `@Cleric` in any channel where Cleric is present to start an on-demand investigation.
* Prefix your message with `!agent-name` to run a specific agent on demand.