omnigent-knowledge

# Omnigent Knowledge Base

## What is Omnigent?

Agent plane is a server that hosts, manages, and executes agents via an
OpenResponses-compatible API. Users create **agent directories** (also
called agent images) that contain configuration, instructions, skills,
and tools. The server loads these directories and serves them via HTTP.

## Agent Directory Layout

```
my-agent/
├── config.yaml          # REQUIRED — agent spec
├── AGENTS.md            # Recommended — instructions/personality
├── skills/              # Optional — load-on-demand skills
│   └── <skill-name>/
│       └── 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)
    └── <agent-name>/
        ├── config.yaml
        └── ...
```

## config.yaml Reference

The only required file. All fields except `spec_version` are optional.

```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 (must match agents/ subdirectories)
  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
```

## Executor Types

| Type | When to use | How it works |
|------|------------|--------------|
| `claude_sdk` | New simple agents; existing Claude SDK code | In-process Anthropic Claude SDK; it manages its own loop |
| `agents_sdk` | New simple agents; existing OpenAI Agents SDK code | In-process OpenAI Agents SDK runner |
| `omnigent` | Coding/CLI harnesses, shell + file tools, sub-agents | Spawns a subprocess harness selected by `config.harness` |

**There is no `llm` executor type** — the only valid values are
`claude_sdk`, `agents_sdk`, and `omnigent`. For **most new simple agents**,
use `claude_sdk` (or `agents_sdk`) — in-process, no extra config. Use
`omnigent` when the agent needs a specific harness, shell/file access, or
sub-agents; it **requires** a `config.harness`:

| `config.harness` | What it is |
|------------------|------------|
| `claude-native` (alias `claude`) | Claude Code — full coding tools, native permissions |
| `claude-sdk` | Claude Agent SDK loop |
| `codex-native` / `codex` | Codex CLI / harness |
| `openai-agents` | OpenAI Agents harness (any gateway model) |
| `open-responses` | OpenResponses-compatible harness |
| `pi` | Headless multi-model worker (bridged `sys_os_*` tools) |

## AGENTS.md Format

Free-form markdown. This becomes the agent's system prompt. Best practices:

- Start with a clear identity statement ("You are a ...")
- List capabilities and constraints
- Reference skills by name ("You have a skill called deep-research")
- Reference sub-agents if any ("You can spawn the fact_checker agent")
- Keep it focused — the model reads this on every turn

## Skills Format

Each skill lives in `skills/<skill-name>/SKILL.md`:

```markdown
---
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...
```

Rules:
- YAML frontmatter with `name` and `description` (both required)
- `name` must match the directory name, be lowercase, use `[a-z0-9-]+`
- Body is ma