How to Configure Subagents with Different Models Using `runAs=subagent` in Reasonix

Set subagent_model for a global default or subagent_models.<skill> for per-skill overrides in your reasonix.toml, and the run_skill tool automatically routes each sub-agent to its designated LLM model.

Reasonix supports sub-agents—isolated child execution loops declared with runAs: subagent in skill files—that can run on different LLM models than the parent agent. This allows you to optimize cost and performance by matching specific models to specific tasks. This guide explains how to configure subagents with different models using runAs=subagent in Reasonix, based on the actual implementation in the esengine/DeepSeek-Reasonix source code.

Model Selection Hierarchy

When a skill runs as a sub-agent, the engine resolves which LLM model (and effort level) to use through a strict three-tier priority system defined in internal/skill/tools.go and internal/config/config.go:

1. Per-skill override – Agent.SubagentModels[skill] in the Reasonix configuration.
2. Global default – Agent.SubagentModel used as a fallback for every sub-agent without a specific entry.
3. Skill front-matter – The model: field inside the skill file itself, consulted only when the configuration provides no value.

If a model is found via the first two methods, the sub-agent’s run_skill tool passes it to the profile resolver (ProfileResolver), which creates an event.Profile containing {Model, Effort}. The resolver is consulted in internal/skill/tools.go (lines 27-30, 33-43), and the selection logic lives in internal/config/config.go where the configuration fields are declared.

Configuration Structure

The configuration schema in internal/config/config.go (lines 764-766) defines the two key fields for sub-agent model management:

type AgentConfig struct {
    SubagentModel  string            `toml:"subagent_model"`   // global default
    SubagentModels map[string]string `toml:"subagent_models"` // per-skill map
}

When run_skill is called for a sub-agent (sk.RunAs == RunSubagent), the runner looks up the model via profileResolver (see profileForSkill in internal/skill/tools.go). If the resolver returns nil, the engine falls back to the configuration map described above.

Global Default vs. Per-Skill Overrides

• Global default model (subagent_model): Defined in internal/config/config.go and used when a skill does not have a per-skill entry.
• Per-skill model overrides (subagent_models): A map that performs look-ups with skillName → model string, allowing fine-grained control over which LLM handles specific sub-agents.

Practical Configuration Examples

Global Default Configuration

Set a global fallback model in your ~/.reasonix/reasonix.toml user-level configuration:

[agent]

# Global default for all sub-agents

subagent_model = "deepseek/deepseek-v4-pro"

Source: internal/config/render.go writes these fields (lines 230-238) and internal/config/config.go stores them (lines 764-766).

Per-Skill Model Overrides

Define specific models for individual skills using the subagent_models map:

[agent]
subagent_model = "deepseek/deepseek-v4-pro"

subagent_models = {
    explore       = "deepseek/deepseek-v4-pro",   # same as global – optional

    review        = "mimo/mimo-pro",              # different model for review

    security_review = "mimo/mimo-pro"
}

The skill name uses the bare identifier, not the “[🧬 subagent]” tag. When the review skill is invoked, the resolver looks up cfg.Agent.SubagentModels["review"] and builds a profile {Model:"mimo/mimo-pro", Effort:"max"}.

Skill Front-Matter (Optional Fallback)

You can specify a model directly in the skill file, which acts as a last-resort fallback:

--- 
description: deep inspection
runAs: subagent
model: "anthropic/claude-2"
effort: max
---
Your instructions here…

If subagent_models.<skill> is not set in the TOML, the engine uses the model declared here. Source: parsing occurs in internal/skill/skill.go (fields Model, Effort).

Invoking a Sub-Agent via run_skill

Trigger the configured model selection by calling run_skill:

{
  "name": "review",
  "arguments": "review the recent PR"
}

In a Reasonix prompt or via the API:

run_skill({"name":"review","arguments":"review the recent PR"})

Because review is marked runAs: subagent, the resolver executes the priority logic: it checks subagent_models["review"], falls back to subagent_model, and finally checks the skill's front-matter if needed. The selected model drives the isolated child LLM loop.

Source: run_skill execution path in internal/skill/tools.go (lines 100-108) and profile creation in profileForSkill (lines 33-44).

Changing the Model at Runtime

Update the global sub-agent model without restarting via the desktop UI:

err := app.SetSubagentModel("anthropic/claude-2")
if err != nil { 
    // handle error
}

The UI calls SetSubagentModel (see desktop/settings_app.go lines 982-994), which writes the value to c.Agent.SubagentModel and persists the TOML file.

Key Implementation Files

File	Purpose
internal/config/config.go	Defines AgentConfig with SubagentModel & SubagentModels
internal/config/render.go	Renders and parses the TOML configuration (writes the subagent_* lines)
internal/skill/tools.go	Implements run_skill and the sub-agent profile resolver (profileForSkill)
internal/skill/skill.go	Parses skill front-matter (model, effort, runAs)
desktop/settings_app.go	UI helpers to change sub-agent model/effort at runtime
internal/boot/boot.go	Consumes the selected model/effort when starting the child loop

Summary

• Priority order: Per-skill config (subagent_models) → Global default (subagent_model) → Skill front-matter.
• Configuration location: ~/.reasonix/reasonix.toml under the [agent] section.
• Runtime resolution: The profileForSkill function in internal/skill/tools.go creates the profile used by the child loop.
• Dynamic updates: Use SetSubagentModel in the desktop UI to change models without restarting.

Frequently Asked Questions

What happens if no model is specified for a sub-agent?

If no per-skill override exists in subagent_models and no global subagent_model is set, the engine checks the skill's front-matter model: field. If that is also absent, the sub-agent inherits the parent agent's model configuration.

Can I change the sub-agent model without restarting Reasonix?

Yes. The desktop application exposes SetSubagentModel (defined in desktop/settings_app.go lines 982-994), which updates c.Agent.SubagentModel and persists the change to the TOML file immediately. This allows runtime switching of the global sub-agent default.

How do I specify the model directly in a skill file?

Add a model: field to the YAML front-matter at the top of your skill markdown file:

---
runAs: subagent
model: "anthropic/claude-2"
---

This value is only consulted if the TOML configuration does not supply a model via subagent_model or subagent_models.

Does the front-matter model override the TOML configuration?

No. The TOML configuration (subagent_models and subagent_model) takes precedence over the skill front-matter. The front-matter model: field acts as a fallback default when no configuration entry exists for that specific skill.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}