Agent YAML Spec: Complete Schema Reference

The agent spec is a single YAML file that defines everything about an Omnigent agent: its system prompt, the harness and model it uses, the tools it can call, the policies that guard its behavior, and the environment it runs in. Pass it directly to omnigent run — no other configuration files are needed for a self-contained agent.

omnigent run path/to/agent.yaml

Top-level fields

Field	Required	Type	Description
`name`	Recommended	string	Stable identifier shown in sessions and logs.
`prompt`	Usually	string	Inline system prompt for the agent.
`instructions`	Optional	string	Inline instructions text or a path to an instructions file (e.g. `AGENTS.md`). Resolved relative to the YAML file’s directory. Takes precedence over `prompt` when set.
`executor`	Recommended	object	Harness, model, and auth settings. See executor.
`tools`	Optional	object	MCP tools, Python function tools, sub-agents, and handoffs. See tools.
`policies`	Optional	object	Guardrails that inspect requests, responses, tool calls, and results. See policies.
`params`	Optional	object	Typed user parameters available to tools and skills. See params.
`os_env`	Optional	object	Enables local OS tools (file reads, writes, edits, shell). See os_env.
`terminals`	Optional	object	Named interactive terminal environments the agent can launch. See terminals.
`async`	Optional	boolean	Whether async work tools are exposed. Defaults to `true`.
`cancellable`	Optional	boolean	Whether the session can be cancelled. Defaults to `true`.
`timers`	Optional	boolean	Whether timer tools are exposed. Defaults to `false`.

executor

The executor block configures which harness and model the agent uses, and how it authenticates.

Sub-field	Required	Type	Description
`harness`	Recommended	string	The agent harness: `claude-sdk`, `openai-agents`, `codex`, etc.
`model`	Optional	string	Model identifier passed to the harness.
`auth`	Optional	object	Authentication credentials. See `auth` sub-fields below.
`auth.type`	Optional	string	Auth provider type, e.g. `databricks` or `api_key`.
`auth.profile`	Optional	string	Databricks CLI profile name when `auth.type` is `databricks`.

Set your Databricks profile under executor.auth. The older top-level executor.profile shorthand is legacy and should not be used in new specs. CLI flags like --harness and --model can override or supply missing executor values for a run.

Claude SDK example

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

OpenAI Agents example

executor:
  harness: openai-agents
  model: gpt-4o
  auth:
    type: api_key

tools

Tools are declared under tools by name. Four tool types are supported.

type: mcp

MCP (Model Context Protocol) servers expose tools over stdio or HTTP.

Sub-field	Required	Type	Description
`type`	Yes	string	Must be `mcp`.
`command`	One of `command`/`url`	string	Executable to launch for a local (stdio) MCP server, e.g. `uv`.
`args`	Optional	list	Arguments passed to the command.
`url`	One of `command`/`url`	string	HTTP URL for a remote MCP server.
`headers`	Optional	object	HTTP headers sent with every request (e.g. `Authorization`). Supports `${VAR}` interpolation.
`tools`	Optional	list	Optional allowlist of tool names to expose from this MCP server.

Local command example:

tools:
  github:
    type: mcp
    command: uv
    args:
      - run
      - python
      - -m
      - my_package.github_mcp
    tools:
      - search_issues
      - get_pull_request

Remote URL example:

tools:
  docs:
    type: mcp
    url: https://example.com/mcp
    headers:
      Authorization: Bearer ${TOKEN}

type: function

A Python callable exposed as an agent tool.

Sub-field	Required	Type	Description
`type`	Yes	string	Must be `function`.
`callable`	One of `callable`/`runtime`	string	Dotted Python import path of the function, e.g. `my_package.tools.summarize_file`.
`description`	Recommended	string	Human-readable description sent to the model.
`parameters`	Optional	object	JSON Schema object describing the function’s parameters.
`runtime`	Optional	string	Set to `client` for client-provided tools; omit `callable` in that case.

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]

type: agent

A sub-agent exposed as a callable tool.

Sub-field	Required	Type	Description
`type`	Yes	string	Must be `agent`.
`description`	Recommended	string	Description of what the sub-agent does.
`prompt`	Optional	string	System prompt for the sub-agent.
`executor`	Optional	object	Harness and model for the sub-agent (same structure as the top-level executor).
`os_env`	Optional	object or `inherit`	OS environment for the sub-agent. Use `inherit` to share the parent’s sandbox.
`pass_history`	Optional	boolean	Whether to pass the parent conversation history to the sub-agent.
`max_sessions`	Optional	integer	Maximum concurrent sub-agent sessions.

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

Special values: `inherit` and `self`

Use tools.<name>: inherit to inherit a specific tool from a parent agent without redeclaring it. Use tools.<name>: self (or spec: self) to create a sub-agent tool that clones the parent agent’s own spec.

policies

Policies inspect requests, responses, tool calls, and tool results and return ALLOW, DENY, or ASK.

Sub-field	Required	Type	Description
`type`	Yes	string	Must be `function`.
`handler`	Yes	string	Dotted Python import path to the callable or factory.
`factory_params`	Optional	object	Key-value arguments passed to a factory at build time. Omit for direct callables.

Direct callable (no parameters):

policies:
  approve_file_ops:
    type: function
    handler: omnigent.policies.builtins.safety.ask_on_os_tools

Factory with parameters:

policies:
  workspace_policy:
    type: function
    handler: my_package.policies.make_workspace_policy
    factory_params:
      allowed_hosts:
        - example.cloud.databricks.com

os_env

Declare os_env to give the agent access to local OS tools (sys_os_read, sys_os_write, sys_os_edit, sys_os_shell).

Sub-field	Required	Type	Description
`type`	Yes	string	Must be `caller_process`.
`cwd`	Optional	string	Working directory for OS tool calls, e.g. `.` for the current directory.
`sandbox`	Optional	object	Sandbox configuration. See sandbox sub-fields.
`sandbox.type`	Optional	string	Sandbox backend: `linux_bwrap` (Linux default), `darwin_seatbelt` (macOS default), or `none` (no sandboxing).
`sandbox.write_paths`	Optional	list	Paths the sandbox allows writing to.
`sandbox.allow_network`	Optional	boolean	Whether network access is allowed inside the sandbox.

You usually don’t need to specify sandbox.type — omit it and Omnigent picks the platform default (linux_bwrap on Linux, darwin_seatbelt on macOS), so the same YAML works across platforms.

With Linux bubblewrap sandbox:

os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: linux_bwrap
    write_paths:
      - .
    allow_network: true

Trusted local development (no sandboxing):

os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: none

Prefer the narrowest filesystem and network access that supports the task. Do not use sandbox.type: none in shared or production environments.

params

Typed user parameters are declared under params and become available to tools and skills at runtime.

params:
  repo_url:
    type: string
    description: The repository to work with.
    required: true
  max_results:
    type: integer
    description: Maximum results to return.
    default: 10

terminals

Named interactive terminal environments the agent can launch during a session.

Sub-field	Required	Type	Description
`command`	Yes	string	Shell or program to launch, e.g. `bash` or `zsh`.
`args`	Optional	list	Arguments to the command, e.g. `[-l]` for a login shell.
`os_env`	Optional	object or `inherit`	OS environment for the terminal. Use `inherit` to share the agent’s sandbox.
`allow_cwd_override`	Optional	boolean	Allow the launcher to override the working directory at launch time.
`allow_sandbox_override`	Optional	boolean	Allow the launcher to weaken the sandbox. Keep `false` unless you intend to allow this.
`scrollback`	Optional	integer	Number of scrollback lines to keep.

terminals:
  bash:
    command: bash
    args: [-l]
    os_env: inherit
    allow_cwd_override: true
    allow_sandbox_override: false
    scrollback: 10000

Complete example

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

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

async: true
cancellable: true

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

terminals:
  zsh:
    command: zsh
    args: [-l]
    os_env: inherit
    allow_cwd_override: true

tools:
  github:
    type: mcp
    url: https://api.githubcopilot.com/mcp/

  repo_search:
    type: function
    description: Search repository files for a pattern.
    callable: my_package.tools.repo_search
    parameters:
      type: object
      properties:
        query:
          type: string
      required: [query]

  reviewer:
    type: agent
    description: Review proposed code changes.
    prompt: |
      You are a careful code reviewer. Focus on correctness, tests, and security.
    executor:
      harness: claude-sdk
      model: databricks-claude-sonnet-4-6
    os_env: inherit

policies:
  rate_limit:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 150
  github_guard:
    type: function
    handler: omnigent.policies.builtins.github.github_policy
    factory_params:
      write_repos:
        - myorg/my-repo
      write_branches:
        - "feature/*"

Validation tips

Prefer instructions: AGENTS.md for long prompts shared with other tooling.
Start from a bundled example such as examples/hello_world.yaml or examples/coding_supervisor.yaml and remove tools you don’t need.

Run the spec before publishing it:

omnigent run path/to/agent.yaml -p "Say hello"

Keep YAML files free of secrets — use ${ENV_VAR} interpolation in headers and auth blocks instead.

Get Started

Core Concepts

Guides

Deployment

Reference

Agent YAML Spec: Complete Schema Reference

Top-level fields

executor

Claude SDK example

OpenAI Agents example

tools

type: mcp

type: function

type: agent

Special values: `inherit` and `self`

policies

os_env

params

terminals

Complete example

Validation tips

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Deployment

Reference

Documentation Index

​Top-level fields

​executor

​Claude SDK example

​OpenAI Agents example

​tools

​type: mcp

​type: function

​type: agent

​Special values: inherit and self

​policies

​os_env

​params

​terminals

​Complete example

​Validation tips

Build docs developers (and LLMs) love

Top-level fields

executor

Claude SDK example

OpenAI Agents example

tools

type: mcp

type: function

type: agent

Special values: `inherit` and `self`

policies

os_env

params

terminals

Complete example

Validation tips