---
title: "Run a Background Agent"
description: "Create a reusable project agent, verify a manual run, and schedule recurring work with optional Slack delivery."
sidebar:
  label: "Background Agents"
seo:
  title: "Run a Background Agent | Judgment How-to"
  description: "Configure Background Agent instructions, execution and approval modes, schedules, run history, and Slack delivery."
---

A Background Agent runs a saved task against your project. Start with a manual
run to check the instructions and evidence, then enable a schedule when the
result is useful enough to repeat.

For a question about the page you are currently viewing, use
[Judgment Agent](/documentation/judgment-agent). For a known per-trace condition
that should trigger an action, use [automations](/documentation/monitoring/automations-and-alerts).

## Prerequisites

- A Judgment project with the data the task should inspect
- Permission to create a Background Agent
- For Slack delivery, a [connected Slack workspace](/documentation/administration/slack)
  and an available destination channel

## Create and verify the agent

1. Open **Background Agents > Agents** and select **New Agent**.
2. Enter a **Name**, such as `Daily monitoring review`, and an optional
   **Description** that tells teammates what the agent owns.
3. Add **Instructions** that define the evidence to inspect, the time window,
   and the expected result. For example:

   ```text
   Review this project's traces from the last 24 hours. Identify the three
   most important recurring failures, cite representative traces, and explain
   why each matters. If the evidence is insufficient, say so. Do not change data.
   ```

4. Leave **Scheduled trigger** off for the first run. Choose an **Agent mode**:
   **Fast** for a lightweight pass or **Deep Research** for more searching and
   reasoning.
5. Choose an **Approval mode**. **Require approval** asks before write tools
   create, update, or delete data. **Auto approve** permits those tools to run
   without approval prompts; organization roles and tool validation still apply.
6. Select **Create**, then **Run now** on the agent's page.
7. Inspect the run's conversation and final answer. Follow its citations and
   confirm that the findings match the requested project and time window.

These approval labels belong to Background Agent settings. The chat controls
use **Ask for writes** and **Auto-allow writes** for the corresponding choices.

- To change future runs, edit the instructions in **Settings** and select **Save**.
- To direct one run, enter a prompt in the agent's composer. This leaves the
  saved instructions unchanged.

## Enable a schedule

- Save the agent's instructions, then enable **Settings > Triggers > Scheduled trigger**.
- Choose a schedule below and **Save**. Clock-based schedules use **PT**
  (`America/Los_Angeles`), including daylight saving changes.
- Check the next scheduled run in the agent's history.

| Schedule mode | Configure |
| --- | --- |
| **Daily/weekly** | Every day, or selected days each week, at a chosen time. |
| **Interval** | One of the offered intervals, from every 15 minutes to every 12 hours. |
| **Advanced** | A valid five-field cron expression. |

## Deliver scheduled results to Slack

With a scheduled trigger enabled, turn on **Slack delivery > Send output to Slack**,
choose channels, and **Save**.

Slack receives the scheduled run's final assistant message, not its full tool
transcript. Check delivery after the next scheduled run; manual **Run now**
does not send scheduled Slack output.

## Inspect history and pause recurring work

- Select a run on the agent's page to read its conversation and status.
  Use **Show more...** for older runs.
- To pause future runs, turn off **Settings > Scheduled trigger** and **Save**.
  This keeps the agent available and does not stop a run already in progress.

Custom-agent owners and organization administrators can manage its settings.
Other readers may see **View settings**. Built-in agents have different
controls; these scheduling steps apply to custom Background Agents.

## Troubleshooting

- If **Run now** is disabled, provide saved instructions or a run prompt and
  check whether a run is already starting.
- If saving is disabled, check the name, instructions, schedule validation,
  and whether you have changed a setting.
- If the schedule fails, inspect any error shown under **Triggers** and the
  run history before assuming the task found nothing.
- If Slack controls are disabled, enable the scheduled trigger first. If the
  channel is unavailable, check the workspace connection and channel access in
  **Settings > Connections**.

## Next step

[Add project Knowledge](/documentation/project-knowledge) for durable context
that the agent should reuse across investigations.