# Configuring Agents and Triggers

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; for alerts, that means a bot message in a configured Slack channel matching the trigger's keywords.

Both are managed under the **Agents** sidebar item in the web app, on the **Agents** and **Triggers** tabs.

{% 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 an alert in a configured channel matches a trigger, 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 tab**

In the Cleric web app, click **Agents** in the sidebar. The **Agents** tab lists built-in agents (read-only) and your custom agents.
{% 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 in response to an event, switch to the **Triggers** tab and add a trigger that routes matching alerts to this agent.
{% 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 routes alerts posted in a Slack channel to a specific agent. When a bot posts a message in a channel where Cleric is a member, Cleric runs the first matching trigger's agent.

### How a trigger fires

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

1. Cleric evaluates triggers in their listed order (top-down) for that channel.
2. For each trigger: if the alert 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 alert 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](/investigation/collaborating-with-cleric.md)).

If the alert matches a recent issue in the same channel, Cleric attaches it to that issue instead of running the agent again. See [Alert Grouping](/investigation/how-investigations-work.md#alert-grouping).

### 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 alerts. 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 alert 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 alerts 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 an alert 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 alerts for the catch-all.

### Adding a trigger

{% stepper %}
{% step %}
**Open the Triggers tab**

In the Cleric web app, click **Agents** in the sidebar, then the **Triggers** tab. Triggers are grouped by Slack channel.
{% 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**. The dialog has three sections:

* **When alert received in**: pick 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**: pick the agent to run.

The Preview block at the bottom updates as you edit and shows the rule in plain English (e.g., *When alert received 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 %}

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cleric.ai/setup/agents-and-triggers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.