Skip to main content

​
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.
Background agents are disabled by default. Set AGENTS_ENABLED=true in your environment to enable this feature.

​
Enabling Background Agents

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

​
Agent Types

​
User Agents

User agents are personal — document search uses the permissions of their creator. The App Access selections constrain source-specific connector and MCP capabilities; unified search can still use any indexed source the creator is permitted to read. User agents are useful for recurring personal tasks like weekly summaries or monitoring specific topics.

​
Org Agents

Org agents have broader access across all connected data sources. Core read-only tools such as search and people lookup remain available; an action whitelist controls optional capabilities such as email sending and connector actions. Only admins can create org agents.
Regular users see and can open an interactive chat only with user agents they created. Admins can also access and chat with organization agents; another user’s personal agent remains owner-only. Scheduled user-agent searches use the creator’s document permissions, while scheduled org-agent searches use organization scope.

​
Available Tools

Agents can use the following tools during execution:
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 optional actions are 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 connector and MCP capabilities to specific connected sources. Document search remains permission-filtered to the creator rather than restricted by this list.search_chats and read_chat use the creator’s user context. They can read a user agent creator’s own previous chats, but scheduled org-agent runs have no user context and cannot access an individual user’s chat history. 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.
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. The Python runtime also includes pandas, numpy, openpyxl, xlsxwriter, python-docx, python-pptx, reportlab, and pypdf, so agents can create Word, PowerPoint, Excel, and PDF files as artifacts. Files written to a chat’s workspace are versioned automatically, so older versions are preserved.

​
Configuration

These environment variables control agent behavior. See Configuration Reference for details.

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