Skip to content

Agent definition schema ​

Parent: Agents and delegation.

This is the parse contract for agent Markdown files. Unknown frontmatter keys and invalid values make the file invalid. Discovery skips an invalid user file and reports it (/agents, rho action agents), so other agents and startup are unaffected. Its agent stays unavailable until fixed: launching that id reports the file's error instead of falling back to a lower-precedence agent with the same id. Field order does not matter; runtime is resolved before tools.

File shape ​

text
---
<yaml-like frontmatter keys>
---
<markdown body>
PartRule
FrontmatterStarts and ends with a line that is exactly ---
BodyMarkdown after the closing ---. Trimmed. Used by prompt
EncodingText file, one agent

Frontmatter fields ​

FieldTypeRequiredDefaultAllowed values / constraints
idstringnofile stem (name in name.md)1-64 chars; lowercase ASCII letters, digits, single hyphens only; no leading/trailing/double hyphen
descriptionstringyes-1-1024 Unicode characters after trim; empty rejected
runtimeenumnorhorho | claude-cli | cursor | antigravity
promptenumnoextendextend | replace. replace requires a non-empty Markdown body. replace is rejected on cursor and antigravity (ACP has no system-prompt override; use extend)
model-policyenumnosee model rulesDepends on runtime (below)
modelstringpolicy-dependentunsetNon-empty; no whitespace. Rho may use @alias. Claude, Cursor, and Antigravity reject @alias; Claude passes the value as the session model option, Cursor passes it to --model, Antigravity sets it as the session model option. Cursor allows brackets and commas, for example gpt-5.3-codex[effort=high,fast=false]
providerstringnounsetNon-empty; no whitespace. Rho only. Rejected on claude-cli, cursor, and antigravity
authstringnounsetAuth profile id (for example xai-oauth, xai-api-key). Rho only. Rejected on claude-cli, cursor, antigravity, and with model-policy: inherit. Must be a known profile; when set with provider, must be valid for that provider
reasoningenumnounset (inherit)Rho: off | minimal | low | medium | high | xhigh | max. Claude: low | medium | high | xhigh | max only (maps to Claude effort). off / minimal rejected on Claude. Rejected on cursor (no reasoning flag; put effort in model) and antigravity (runs use agy's default thinking level)
fastboolnofalsetrue | false. Rho only, and requires a pinned model (not model-policy: inherit). Turns on fast serving for this agent, independent of the parent's /fast. Bind fails when the resolved provider, model, and auth do not support fast mode (Codex GPT-5.5+/GPT-6, SpaceXAI OAuth grok-4.7). For SpaceXAI, pin auth: xai-oauth; with auth unset bind may select the API-key login
toolsall or string listnoruntime-specificSee tool vocabulary. Mixing Rho, Claude, Cursor, and Antigravity names is a parse error. Required and nonempty on cursor and antigravity
inherit_claude_configboolnofalsetrue | false. true only with runtime: claude-cli

Scalars are plain or single/double quoted. Booleans are only true / false. Lists use [a, b] form (comma-separated). Nested YAML maps/objects are not accepted.

Model rules by runtime ​

Model selection depends on runtime. Rho can inherit or pin host models. Claude-cli and Cursor pass model names through and reject Rho-only fields.

runtime: rho (default)

model-policymodelproviderauthResult
omitted, no modelomittedomittedomittedinherit
omitted, with modelrequiredoptionaloptionaltreated as select
inheritmust omitmust omitmust omitkeep parent provider/model/auth
prefer | require | selectrequiredoptionaloptionalpin that selection; @alias allowed. Unset auth keeps a compatible parent auth mode, otherwise selects an available host login for the target provider, falling back to the provider default when none is available

The editor's host auth choice leaves auth unset. For example, an SpaceXAI agent can use your signed-in xai-oauth login even when its parent runs on Codex. When switching providers, available credentials follow the model picker's preference order. An explicit auth pin always wins, even if another login is available.

runtime: claude-cli

model-policymodelprovider / authResult
omitted / inherit, no modelomittedmust omitClaude default model (no --model)
omitted / select, with modelrequiredmust omitpass-through --model
prefer | require--rejected
any@...-rejected (no Rho alias resolution)
anyanysetrejected

runtime: cursor

model-policymodelprovider / authResult
omitted / inherit, no modelomittedmust omitCursor default model (no --model)
omitted / select, with modelrequiredmust omitpass-through --model
prefer | require--rejected
any@...-rejected (no Rho alias resolution)
anyanysetrejected

Cursor has no --effort / reasoning flag. Put effort in the model id (gpt-5.3-codex-high) or a bracket override (claude-opus-5[effort=high,fast=false]). Brackets and commas are allowed; whitespace is not.

model: values are 1:1 with cursor-agent models ids. Rho caches that account-scoped list for 24 hours (refresh on /login cursor, /doctor, and lazily in the agent editor). The editor groups by display-name family and offers Other… to type an id or bracket override. A pin that is missing from a non-empty cache warns at bind and still runs.

runtime: antigravity

model-policymodelprovider / authResult
omitted / inherit, no modelomittedmust omitserver default model
omitted / select, with modelrequiredmust omitsession model option set before the prompt
prefer | require--rejected
any@...-rejected (no Rho alias resolution)
anyanysetrejected

Antigravity has no reasoning setting; runs use agy's default thinking level. model is an agy model such as gemini-3.8-flash or gemini-4-argon. A model the server does not offer fails the run before the prompt and lists the offered values.

Tool vocabulary by runtime ​

Tool lists are not shared across runtimes. Mixing Rho capability names, Claude tool entries, Cursor tool names, and Antigravity built-in names is a parse error.

runtime: rho

FormMeaning
omitted or tools: allall host-supplied Rho capabilities (default)
tools: [name, ...]allowlist of Rho capabilities

Built-in Rho capability names:

text
agent
agents
bash
edit
fetch_content
get_search_content
glob
grep
list_dir
powershell
process
questionnaire
read_file
rho
shell
skill
todo
ui
web_search
write

Notes:

  • shell resolves at bind time to the platform shell (bash or powershell) when that capability is available
  • unknown names become extension capabilities and still fail bind unless the host supplies them
  • delegated agents never receive agent / agents / advisor even if listed
  • questionnaire is offered on delegated Rho runs when a parent session can answer; if the host cannot offer it for that launch, bind omits it instead of failing
  • ui is offered only to a daemon session whose client draws surfaces, never to a delegated run; elsewhere bind omits it instead of failing

runtime: claude-cli

FormMeaning
omittedempty allowlist (no Claude tools)
tools: allrejected
tools: [entry, ...]Claude Code tool entries

Each entry must match:

text
ToolName
ToolName(specifier)
RuleDetail
Base namenon-empty; letters, digits, _, - only
Specifieroptional (...) with balanced parentheses; may contain spaces and quotes
Commasnot allowed inside a specifier (Claude list grammar cannot round-trip them)
Membershipparse is open-ended (plugins/MCP may add tools); Rho checks shape, not a fixed catalog. Auto and Allow edits fail closed at spawn unless every base name is a proven no-prompt Claude built-in for that Rho approval class
ExamplesRead, Edit, Glob, Grep, Bash(git *), mcp__server__tool

Base names feed the Claude tools session option. A specifier such as Bash(git *) still lists Bash there. Every declared entry also goes to allowedTools, which runs listed tools without prompting, so Auto and Allow edits run only when every declared tool is a proven no-prompt Claude built-in for that Rho approval class (read/network names such as Read, Glob, Grep, WebSearch). Write, process, specifier, unknown, plugin, and MCP names fail closed. Plan and Bypass still accept any well-shaped name. Nested Claude Task stays disallowed at spawn.

runtime: cursor

FormMeaning
omittedrejected (tools is required)
tools: allrejected. Cursor enables every tool by default and Rho fences only classified names
tools: []rejected (need at least one classified tool)
tools: [name, ...]closed allow list; each run derives Cursor's fence from it (Permission modes)

Accepted snake_case names (this is the whole set):

text
read_tool_call
grep_tool_call
glob_tool_call
ls_tool_call
sem_search_tool_call
read_lints_tool_call
edit_tool_call
delete_tool_call
shell_tool_call
write_shell_stdin_tool_call
web_search_tool_call
web_fetch_tool_call
fetch_tool_call
mcp_tool_call
list_mcp_resources_tool_call
read_mcp_resource_tool_call
update_todos_tool_call
read_todos_tool_call
create_plan_tool_call
apply_agent_diff_tool_call

Deliberately absent: task_tool_call (nested fan-out), ask_question_tool_call (no headless answer path), switch_mode_tool_call (could leave plan mode), and computer-use / screen / cloud / PR tools.

runtime: antigravity

FormMeaning
omittedrejected (tools is required)
tools: allrejected. agy offers every built-in to an agent without a list
tools: []rejected (need at least one built-in)
tools: [name, ...]closed allow list, written as the tools: of the run's agy custom agent (Permission modes)

Accepted names (this is the whole set):

text
read_file
write_file
edit_file
run_command
search_web

Deliberately absent: invoke_subagent, define_subagent, manage_subagents, and send_message (nested agents outside Rho's run), schedule (timers that outlive the run), ask_question (no headless answer path), and generate_image. agy always adds manage_task, which manages the agent's own background commands.

Names from the earlier agy_acp_server runtime (view_file, create_file, read_url_content) fail to parse; use read_file and write_file.

Body / prompt semantics ​

promptBody emptyBody non-empty
extend (default)keep base coding prompt onlyappend body to base coding prompt
replaceparse errorbody becomes the full system prompt. Rejected on runtime: cursor and runtime: antigravity

JSON Schema (frontmatter) ​

Machine-readable shape for the frontmatter object after parse. Runtime-specific exclusions (provider on Claude and Cursor, tools: all on Claude and Cursor, reasoning on Cursor, reasoning: off|minimal on Claude, prompt: replace on Cursor, and model-policy combinations) are enforced in prose and by the Rho parser beyond plain JSON Schema.

json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://rho.dev/schemas/agent-definition-frontmatter.json",
  "title": "Rho agent definition frontmatter",
  "type": "object",
  "additionalProperties": false,
  "required": ["description"],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024
    },
    "runtime": {
      "type": "string",
      "enum": ["rho", "claude-cli", "cursor", "antigravity"],
      "default": "rho"
    },
    "prompt": {
      "type": "string",
      "enum": ["extend", "replace"],
      "default": "extend"
    },
    "model-policy": {
      "type": "string",
      "enum": ["inherit", "prefer", "require", "select"]
    },
    "model": {
      "type": "string",
      "minLength": 1,
      "pattern": "^\\S+$"
    },
    "provider": {
      "type": "string",
      "minLength": 1,
      "pattern": "^\\S+$"
    },
    "auth": {
      "type": "string",
      "minLength": 1,
      "pattern": "^\\S+$"
    },
    "reasoning": {
      "type": "string",
      "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max"]
    },
    "tools": {
      "oneOf": [
        { "const": "all" },
        {
          "type": "array",
          "items": { "type": "string", "minLength": 1 },
          "uniqueItems": true
        }
      ]
    },
    "inherit_claude_config": {
      "type": "boolean",
      "default": false
    },
    "fast": {
      "type": "boolean",
      "default": false
    }
  },
  "allOf": [
    {
      "if": {
        "properties": { "runtime": { "const": "claude-cli" } },
        "required": ["runtime"]
      },
      "then": {
        "properties": {
          "provider": false,
          "auth": false,
          "fast": false,
          "model-policy": { "enum": ["inherit", "select"] },
          "reasoning": { "enum": ["low", "medium", "high", "xhigh", "max"] },
          "tools": {
            "type": "array",
            "items": { "type": "string", "minLength": 1 }
          },
          "inherit_claude_config": { "type": "boolean" }
        },
        "not": {
          "required": ["model-policy", "model"],
          "properties": {
            "model-policy": { "const": "inherit" },
            "model": true
          }
        }
      }
    },
    {
      "if": {
        "properties": { "runtime": { "const": "cursor" } },
        "required": ["runtime"]
      },
      "then": {
        "required": ["tools"],
        "properties": {
          "provider": false,
          "auth": false,
          "prompt": { "const": "extend" },
          "model-policy": { "enum": ["inherit", "select"] },
          "reasoning": false,
          "fast": false,
          "inherit_claude_config": false,
          "tools": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "read_tool_call",
                "grep_tool_call",
                "glob_tool_call",
                "ls_tool_call",
                "sem_search_tool_call",
                "read_lints_tool_call",
                "edit_tool_call",
                "delete_tool_call",
                "shell_tool_call",
                "write_shell_stdin_tool_call",
                "web_search_tool_call",
                "web_fetch_tool_call",
                "fetch_tool_call",
                "mcp_tool_call",
                "list_mcp_resources_tool_call",
                "read_mcp_resource_tool_call",
                "update_todos_tool_call",
                "read_todos_tool_call",
                "create_plan_tool_call",
                "apply_agent_diff_tool_call"
              ]
            }
          }
        },
        "not": {
          "required": ["model-policy", "model"],
          "properties": {
            "model-policy": { "const": "inherit" },
            "model": true
          }
        }
      }
    },
    {
      "if": {
        "properties": { "runtime": { "const": "antigravity" } },
        "required": ["runtime"]
      },
      "then": {
        "required": ["tools"],
        "properties": {
          "provider": false,
          "auth": false,
          "prompt": { "const": "extend" },
          "model-policy": { "enum": ["inherit", "select"] },
          "reasoning": false,
          "fast": false,
          "inherit_claude_config": false,
          "tools": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "read_file",
                "write_file",
                "edit_file",
                "run_command",
                "search_web"
              ]
            }
          }
        },
        "not": {
          "required": ["model-policy", "model"],
          "properties": {
            "model-policy": { "const": "inherit" },
            "model": true
          }
        }
      }
    },
    {
      "if": {
        "properties": { "model-policy": { "const": "inherit" } },
        "required": ["model-policy"]
      },
      "then": {
        "not": {
          "anyOf": [
            { "required": ["model"] },
            { "required": ["provider"] },
            { "required": ["auth"] },
            { "required": ["fast"] }
          ]
        }
      }
    },
    {
      "if": {
        "properties": {
          "model-policy": { "enum": ["prefer", "require", "select"] }
        },
        "required": ["model-policy"]
      },
      "then": { "required": ["model"] }
    }
  ]
}

Examples ​

Rho agent:

markdown
---
id: security-review
description: Reviews changes for security defects
runtime: rho
model-policy: inherit
reasoning: high
tools: [read_file, list_dir, bash]
---
Review the requested changes. Do not modify files.

Rho agent with pinned provider and OAuth auth:

markdown
---
id: worker
description: Implements delegated tasks
runtime: rho
model-policy: prefer
model: grok-4.7
provider: xai
auth: xai-oauth
reasoning: medium
fast: true
tools: all
---
Complete the delegated task fully before finishing.

Claude Code delegated agent:

markdown
---
id: claude-planner
description: Plans with Claude Code on the user subscription
runtime: claude-cli
model: claude-opus-5
reasoning: high
tools: [Read, Edit, "Bash(git *)"]
inherit_claude_config: false
---
Produce a short plan. Prefer reading before editing.

Cursor Agent delegated agent:

markdown
---
id: cursor-reviewer
description: Reviews with Cursor Agent on a closed read/edit allow list
runtime: cursor
model: "gpt-5.3-codex[effort=high,fast=false]"
tools: [read_tool_call, grep_tool_call, glob_tool_call, edit_tool_call]
---
Review the requested changes. Prefer reading before editing.

Antigravity delegated agent:

markdown
---
id: agy-reviewer
description: Reviews with Antigravity on a read and shell allow list
runtime: antigravity
model: gemini-3.8-flash
tools: [read_file, run_command]
---
Review the requested changes. Prefer reading before editing.

Unknown fields, values, and tool references make the file invalid, so its agent never executes. Definitions contain no credentials or mutable runtime state. New sessions store a v2 semantic fingerprint over behaviorally relevant fields, including runtime, tools, inherit_claude_config, and fast when enabled, not file paths or formatting. Resume also accepts the exact pre-runtime-axis v1 fingerprint for unchanged default Rho definitions (runtime: rho, inherit_claude_config: false, Rho tools encoding). Real definition changes still fail resume.