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.
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_ENABLEDenvironment variable totruein your.envfile:
- 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.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.
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) |
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.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.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
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