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

# Background Agents

> Configure scheduled AI agents that run tasks automatically

## Overview

Background agents are scheduled AI agents that execute tasks automatically on a recurring basis. They can search across your connected sources, look up people, and send emails — all without manual interaction.

<Note>
  Background agents are disabled by default. Set `AGENTS_ENABLED=true` in your environment to enable this feature.
</Note>

## Enabling Background Agents

1. Set the `AGENTS_ENABLED` environment variable to `true` in your `.env` file:

```bash theme={null}
AGENTS_ENABLED=true
```

2. Restart your services

## Agent Types

| Type           | Scope        | Description                                                      |
| -------------- | ------------ | ---------------------------------------------------------------- |
| **User Agent** | Personal     | Runs on behalf of a single user, scoped to their allowed sources |
| **Org Agent**  | Organization | Runs with access to all data, with an explicit action whitelist  |

### User Agents

User agents are personal — they run with the permissions of their creator and can only access sources the user has specified. Useful for recurring personal tasks like weekly summaries or monitoring specific topics.

### Org Agents

Org agents have broader access across all connected data sources. They use an action whitelist to control which tools they can use (e.g., search, people lookup, email sending). Only admins can create org agents.

<Note>
  Any user can open an **interactive chat** with any agent (user or org) from the agent's detail page — not just the creator, and not just for org agents. The scheduled background runs still execute with the creator's permissions; interactive chat runs with the viewer's own permissions, so results in interactive sessions are always filtered by what the viewing user is allowed to see.
</Note>

## Available Tools

Agents can use the following tools during execution:

| Tool                             | Description                                                                     |
| -------------------------------- | ------------------------------------------------------------------------------- |
| **search\_documents**            | Search across connected sources using the same index as the UI                  |
| **read\_document**               | Fetch full text of a document (emails, Slack threads, Jira tickets, etc.) by ID |
| **read\_file** / **write\_file** | Read and write files inside the sandbox workspace                               |
| **run\_bash**                    | Execute a bash command inside the sandbox                                       |
| **run\_python**                  | Execute a Python snippet inside the sandbox                                     |
| **send\_email**                  | Send an email via the configured email provider (org agents only)               |

<Note>
  Unlike interactive chat, background agents run without a human in the loop, so **there is no per-tool approval prompt**. Instead, what an agent is allowed to do is decided at creation time: org agents have an `allowed_actions` whitelist that controls which tools are even registered (for example, `send_email` is only available if it was added to the whitelist), and user agents have an `allowed_sources` list that scopes the search and document tools to specific connected sources.
</Note>

<Note>
  `run_bash` and `run_python` execute inside the `omni-sandbox` container, which is isolated from the rest of your infrastructure. The sandbox has a preloaded set of CLI tools (including an Excel-to-text converter) and disposable file storage per run.
</Note>

## Configuration

These environment variables control agent behavior. See [Configuration Reference](/deployment/configuration#background-agents-configuration) for details.

| Variable                        | Default | Description                                     |
| ------------------------------- | ------- | ----------------------------------------------- |
| `AGENT_SCHEDULER_POLL_INTERVAL` | `30`    | Seconds between scheduler checks for due agents |
| `AGENT_MAX_CONCURRENT_RUNS`     | `3`     | Maximum agents running simultaneously           |
| `AGENT_MAX_ITERATIONS`          | `15`    | Maximum tool calls per agent run                |

## Creating an Agent

1. Navigate to the **Agents** section in the Omni sidebar
2. Click **Create Agent**
3. Configure the agent:
   * **Name**: A descriptive name for the agent
   * **Prompt**: Instructions for what the agent should do
   * **Schedule**: Cron expression or interval (e.g., every 6 hours, daily at 9am)
   * **Type**: User or Org
   * **Model**: Optionally select a specific LLM model
4. Click **Save**

The agent will run automatically according to its schedule. You can view run history and results in the agent's detail page.

## Monitoring

Each agent run is tracked with:

* **Status**: Pending, Running, Completed, or Failed
* **Summary**: An auto-generated summary of what the agent accomplished
* **Duration**: How long the run took
* **Tool calls**: Number of tool invocations during the run

Navigate to an agent's detail page to view its run history and outputs.