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

> Learn to configure Reasonix subagents with different models using runAs=subagent. Master multi-model LLM routing for your skills via reasonix.toml configuration.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-06-24

---

**Set `subagent_model` for a global default or `subagent_models.<skill>` for per-skill overrides in your [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/tools.go) and [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/tools.go) (lines 27-30, 33-43), and the selection logic lives in [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go) where the configuration fields are declared.

## Configuration Structure

The configuration schema in [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go) (lines 764-766) defines the two key fields for sub-agent model management:

```go
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```toml
[agent]

# Global default for all sub-agents

subagent_model = "deepseek/deepseek-v4-pro"

```

*Source:* [`internal/config/render.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/render.go) writes these fields (lines 230-238) and [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go) stores them (lines 764-766).

### Per-Skill Model Overrides

Define specific models for individual skills using the `subagent_models` map:

```toml
[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:

```markdown
--- 
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/skill.go) (fields `Model`, `Effort`).

### Invoking a Sub-Agent via `run_skill`

Trigger the configured model selection by calling `run_skill`:

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

```

In a Reasonix prompt or via the API:

```go
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

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

```

The UI calls `SetSubagentModel` (see [`desktop/settings_app.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go) | Defines `AgentConfig` with `SubagentModel` & `SubagentModels` |
| [`internal/config/render.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/render.go) | Renders and parses the TOML configuration (writes the `subagent_*` lines) |
| [`internal/skill/tools.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/tools.go) | Implements `run_skill` and the sub-agent profile resolver (`profileForSkill`) |
| [`internal/skill/skill.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/skill.go) | Parses skill front-matter (`model`, `effort`, `runAs`) |
| [`desktop/settings_app.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/settings_app.go) | UI helpers to change sub-agent model/effort at runtime |
| [`internal/boot/boot.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

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