Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/omnigent-ai/omnigent/llms.txt

Use this file to discover all available pages before exploring further.

Every Omnigent agent is a short YAML file that describes its harness and model, system prompt, tools, optional sub-agents, and policies. You can write the file by hand or generate it by asking any agent in chat — describe the agent you want and it authors the file for you. Once you have a file, run it with a single command.

​
Minimal agent

The minimal spec declares a name, a prompt, and an executor with a harness. Everything else is optional. 
name: hello_agent
prompt: |
  You are a concise assistant. Answer directly and ask a follow-up question when
  the request is ambiguous.

executor:
  harness: claude-sdk
  model: databricks-claude-sonnet-4-6
  auth:
    type: databricks
    profile: oss

​
Choosing a harness

Set executor.harness to one of the supported harnesses. CLI flags --harness and --model can override or supply missing values at run time.
HarnessDescription
claude-sdkClaude Agent SDK — Omnigent’s managed Claude harness
openai-agentsOpenAI Agents SDK — for GPT and compatible models
codexCodex CLI in SDK (relay) mode
piPi harness — read-only/explore specialist, supports any gateway model
claude-nativeWraps the claude CLI directly via tmux
codex-nativeWraps the codex CLI directly via tmux
Native harnesses (claude-native, codex-native) wrap the real CLI in a tmux session that you can attach to and watch in real time. SDK harnesses run headless and relay tool calls through Omnigent.

​
Writing the system prompt

Use prompt for a short prompt written directly in the YAML:
prompt: |
  You are a helpful data analyst. Use only the tools you have been given.

​
Adding tools

Tools are declared under a top-level tools key, keyed by name.

​
MCP server tools

Point at a local MCP server process or a remote URL: 
tools:
  github:
    type: mcp
    command: uv
    args:
      - run
      - python
      - -m
      - my_package.github_mcp
    tools:
      - search_issues
      - get_pull_request

​
Python function tools

Point at any importable Python callable. Omnigent generates the JSON schema from the function signature, or you can declare it manually: 
tools:
  summarize_file:
    type: function
    description: Summarize a local text file.
    callable: my_package.tools.summarize_file
    parameters:
      type: object
      properties:
        path:
          type: string
      required: [path]
For client-provided tools, use runtime: client and omit callable.

​
Sub-agent tools

Embed a full agent as a tool. A supervisor can delegate tasks to it via sys_session_send: 
tools:
  reviewer:
    type: agent
    description: Review proposed code changes.
    prompt: |
      You are a careful code reviewer. Focus on correctness, tests, security,
      and maintainability.
    executor:
      harness: claude-sdk
      model: databricks-claude-sonnet-4-6
    os_env: inherit
    pass_history: true
    max_sessions: 2
Use tools.<name>: inherit to inherit a tool from a parent agent, or tools.<name>: self for a sub-agent that clones the parent spec.

​
Local OS access

Declare os_env when the agent needs to read files, write files, or run shell commands. Omit sandbox.type to let Omnigent pick the platform default (linux_bwrap on Linux, darwin_seatbelt on macOS): 
os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: linux_bwrap
    write_paths:
      - .
    allow_network: true
For trusted local development you can disable sandboxing entirely: 
os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: none
Prefer the narrowest filesystem and network access that supports the task. Do not pass secrets through the environment unless a tool genuinely needs them.

​
Policies in the agent spec

Policies are declared under a top-level policies key and evaluated in declaration order for every action the agent takes. They apply to every session that uses this agent spec: 
policies:
  approve_shell:
    type: function
    handler: omnigent.policies.builtins.safety.ask_on_os_tools   # ask before shell / file writes
  cap_calls:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 50                    # cap how many tools one session can call
  budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00           # hard spend cap...
      ask_thresholds_usd: [3.00]   # ...with a soft warning on the way
See the Policies guide for the full catalog and trust model.

​
Running the agent

omnigent run path/to/agent.yaml
Override the harness or model at run time without editing the file: 
omnigent run path/to/agent.yaml --harness openai-agents
omnigent run path/to/agent.yaml --harness claude-sdk --model claude-opus-4-8
You can also pass a prompt directly for non-interactive runs: 
omnigent run path/to/agent.yaml -p "Say hello"

​
Example agents

Two example agents ship in the Omnigent repository and make excellent starting points.
Polly is a tech lead that writes no code herself. She plans, delegates all coding work to Claude Code, Codex, or Pi sub-agents running in parallel git worktrees, then routes each diff to a reviewer from a different vendor.
omnigent run examples/polly/
Debby sends every question to both a Claude sub-agent and a GPT sub-agent and displays the answers side by side. Type /debate to have them critique each other before converging. Requires both a Claude and an OpenAI credential.
omnigent run examples/debby/
Run either example on a different harness with --harness. Sub-agents keep their own harness declarations: 
omnigent run examples/polly/ --harness pi
omnigent run examples/debby/ --harness openai-agents

Full Agent YAML spec

Complete reference for every field in the agent YAML: executor, tools, terminals, os_env, policies, and more.

Policies guide

Declare guardrails that allow, deny, or ask before any agent action — at the server, spec, or session level.

Build docs developers (and LLMs) love

Get started for freeTalk to us