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
- Set the
AGENTS_ENABLED environment variable to true in your .env file:
- 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.
Agents can use the following tools during execution:
| Tool | Description | Availability |
|---|
| Search | Search across connected sources | All agents |
| People Search | Look up people in your organization | All agents |
| Document Reader | Read and process documents, emails, Slack threads, Jira tickets, etc. | All agents |
| Email | Send emails (with configured email provider) | Org agents only |
Configuration
These environment variables control agent behavior. See Configuration Reference 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
- Navigate to the Agents section in the Omni sidebar
- Click Create Agent
- 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
- 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.
