Omnigent Knowledge Base

my-agent/
├── config.yaml          # REQUIRED — agent spec
├── AGENTS.md            # Recommended — instructions/personality
├── skills/              # Optional — load-on-demand skills
│   └── <dir>/           # Free-form; skill name comes from SKILL.md
│       └── SKILL.md
├── tools/               # Optional — packaged tools
│   ├── python/          # Local Python tools (auto-discovered *.py)
│   ├── typescript/      # Local TypeScript tools (auto-discovered *.ts)
│   └── mcp/             # MCP server declarations (*.yaml)
└── agents/              # Optional — sub-agent directories (recursive)
    └── <dir>/           # Free-form; sub-agent name comes from config.yaml
        ├── config.yaml
        └── ...

spec_version: 1               # REQUIRED, must be 1

name: my-agent                # Display name
description: Does X and Y.    # One-line summary

# Instructions — path to a file or inline text.
# Default: looks for AGENTS.md in the agent directory.
instructions: AGENTS.md

executor:
  # REQUIRED area. type must be one of: claude_sdk | agents_sdk | omnigent.
  # There is NO `llm` executor type.
  type: claude_sdk     # Anthropic Claude SDK, in-process (simplest)
  # type: agents_sdk   — OpenAI Agents SDK, in-process
  # type: omnigent     — subprocess harness; requires config.harness below

  # Only for type: omnigent — pick the harness that runs the loop.
  # One of: claude-native | claude-sdk | codex-native | codex |
  #         openai-agents | open-responses | pi
  # config:
  #   harness: claude-native
  #   permission_mode: bypassPermissions   # claude-native headless
  #   yolo: true                           # codex-native headless

  # Model is OPTIONAL — omit to use the configured provider's default.
  # Pin one directly on the executor when needed:
  # model: anthropic/claude-sonnet-4-20250514   # LiteLLM provider/model
  # model: databricks-claude-opus-4-7           # or a serving-endpoint name
  # connection:                                 # provider credentials
  #   api_key: ${ANTHROPIC_API_KEY}
  # auth:                                        # or Databricks profile auth
  #   type: databricks
  #   profile: oss

  timeout: 3600        # Task deadline in seconds (default: 3600)
  max_iterations: 1000 # Max LLM calls per task (default: 1000)

# os_env — grant filesystem/shell access (harness agents). Exposes
# sys_os_read / sys_os_write / sys_os_edit / sys_os_shell.
os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: none         # or linux_bwrap / darwin_seatbelt to sandbox

# guardrails — runtime policy gates (optional).
guardrails:
  ask_timeout: 86400   # seconds to wait on an approval prompt
  policies:
    blast_radius:
      type: function
      function:
        path: omnigent.inner.nessie.policies.blast_radius

interaction:
  conversational: true   # Maintain turn history (default: true)
  modalities:
    input: [text, image, file]   # default: [text]
    output: [text]               # default: [text]

tools:
  # Sub-agents this agent can spawn (declared names of agents/ sub-agents)
  agents:
    - researcher
    - summarizer

  # Built-in tools — string name or dict with config
  builtins:
    - web_search                 # auto-detects backend based on model provider
    - terminal_run               # persistent bash shell scoped to the conversation
    - upload_file
    - search_conversations

  timeout: 60          # Default tool timeout in seconds

params:                # Arbitrary key-value (readable by skills/tools)
  max_results: 10

---
name: deep-research
description: Investigate a topic in depth using web search and source synthesis.
---

When researching a topic:

1. Search broadly first using web search...
2. Cross-reference multiple sources...

my-agent/
  tools/
    mcp/
      github.yaml
      slack.yaml

transport: http
url: https://mcp-server.example.com/sse
headers:
  Authorization: Bearer ${GITHUB_TOKEN}