Custom Agents

A custom agent is defined in a short YAML file. No imperative code, no framework subclassing. The YAML file is the agent. You get the entire Omnigent platform for free: web UI, persistent sessions, team collaboration, deployment infrastructure, and contextual policies.

Create it with your coding agent

The recommended way to create a custom agent is to ask your coding agent to build it for you in natural language:

You: Build me a documentation reviewer agent. It should use Claude as
     the model, have access to the file system and GitHub, and follow
     our style guide at docs/STYLE.md.

Agent: Created "docs-reviewer" agent. Opening a new session with it now.
       You can select it from the session dropdown anytime.

The agent writes the YAML behind the scenes and registers it so you can reuse it. If you want to tweak the config later, the YAML file is there to edit directly. For an agent you've installed on a server, you can also change its description, instructions, model, harness, or MCP servers without re-uploading the bundle; see Edit an installed agent's configuration. to edit directly, or you can edit it from the web UI.

Edit an agent in the web UI

Agents you own can be edited in place from Settings › Custom agents (/settings/custom-agents/<agent-id>) without reinstalling a bundle. Open an agent's summary and choose Edit. The Edit button appears only for agents you own, and only when the server advertises configuration editing (agent_config_edit: true in /v1/info); on an older server the summary says to update the server instead. Server-provided agents are read-only.

The Settings page itself is a gated release feature: an operator enables it deployment-wide by including custom_agents_settings_ui in the server's release features (OMNIGENT_FEATURES=custom_agents_settings_ui).

The Edit dialog loads the agent's current configuration and lets you change:

Description, Harness, and Model. The agent's name stays the same. Model and harness compatibility is checked by the server when you save, so an incompatible pair is reported as a save error rather than in the form.
Instructions — the agent's literal instruction text.
MCP servers — add an HTTP or stdio server (Add server), change a server's description, URL, or command and arguments, or mark a server for removal (Remove server / Undo removal). An existing server's name and transport can't be changed, and managed servers are shown read-only.

Credentials (HTTP Headers or stdio Environment variables) are never read back into the editor — only their names are shown. Each configured value defaults to Configured · keep; switch it to Replace to enter a new value or Remove to delete it. Changing a server's URL or command leaves its configured credentials untouched.

Saving sends only the fields you changed. Save changes stays disabled until something differs from the loaded configuration, and changes apply to sessions using the agent on their next turn.

If the agent was changed elsewhere (for example in another tab) before you save, the dialog keeps your draft and asks you to Reload latest. Reloading, Cancel, Escape, and closing the dialog all ask for confirmation while you have unsaved changes (Keep editing / Discard changes). A browser refresh warns about an unsaved draft, but navigating with browser history can discard it.

The config file

Every custom agent lives in its own directory with a config.yaml at the root. You can place the directory anywhere on disk. Run it with:

omni run ./my-agent/              # directory containing config.yaml

What you can configure

The config file supports these sections:

Harnesses

The harness is the runtime that executes your agent loop. Swap one line to switch runtimes.

executor:
  type: omnigent
  config:
    harness: claude

Models & Credentials

Pick the LLM that powers your harness.

executor:
  type: omnigent
  config:
    harness: claude
  model: claude-sonnet-4-6

Prompts & Skills

Set the system prompt inline, or point at a file.

prompt: You are a concise coding assistant.

# Or from a file:
instructions: AGENTS.md

MCP & Tools

Wire in MCP servers, Python functions, or sub-agents.

tools:
  github:
    type: mcp
    command: uv
    args: [run, python, -m, github_mcp]
  summarize:
    type: function
    callable: my_package.tools.summarize_file

Policies

Declarative guardrails in YAML.

policies:
  rate_limit:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 50

Putting it all together

spec_version: 1
name: coding_agent
prompt: |
  You are a coding agent. Inspect files before editing, run targeted tests,
  and summarize changes with validation results.

executor:
  type: omnigent
  config:
    harness: claude
  model: claude-sonnet-4-6

os_env:
  type: caller_process
  cwd: .
  sandbox:
    write_paths: [.]
    allow_network: true

tools:
  repo_search:
    type: function
    callable: my_package.tools.repo_search

policies:
  rate_limit:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 50