> ## 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)                                              |
| **web\_search**                  | Search the public web with the admin-configured current search provider                                        |
| **fetch\_web\_page**             | Fetch readable content from public HTTP(S) URLs with the admin-configured current fetch provider               |
| **Connector actions**            | Source-specific actions exposed by connectors, including MCP-backed resources/prompts and provider API actions |

<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` or a connector action is only available if it was added to the whitelist), and user agents have an `allowed_sources` list that scopes the search, document, and connector-action tools to specific connected sources.

  Connector actions that require per-user OAuth need the relevant user credential to exist before a background run can use them; background runs cannot pause for a connection prompt the way interactive chat can. Web tools require providers to be configured in **Settings** → **Web Providers**; fetches reject localhost, private/internal IP targets, and domains or URL prefixes on the admin blocklist.
</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                |

## Memory

When Memory is enabled and the organization default is **Full memory**, background agents can use memory from prior runs as context for future runs. Agent memory is stored under the agent's own namespace, separate from user chat memory.

Admins configure the organization default and memory model from **Settings** → **Memory**. Users can lower their own memory mode for interactive chats, but the admin default is the maximum available mode.

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