> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Switch model families with presets

> Run the same agent across Qwen, Kimi, DeepSeek, and other model families using family presets — without rewriting agent code.

Family presets (pre-configured defaults for a model family) let you switch model families with minimal code changes. This tutorial shows you how to build an agent that runs on multiple families, override a preset when you need to, and compare the results in qita.

## Step 1 — Build a model with a preset

The fastest way to get a model configured for a specific family is `build_model_for_preset`:

```python theme={null}
from qitos.harness import build_model_for_preset

llm = build_model_for_preset(
    model_name="Qwen/Qwen3-8B",
    api_key="sk-...",
    base_url="https://api.siliconflow.cn/v1/",
)
```

This returns a fully configured model object with the Qwen family preset already applied — the right protocol, parser, tool delivery mode, and context window.

## Step 2 — Run the same agent with different families

The key insight is that your agent code does not change. Only the model construction changes:

```python theme={null}
from qitos.harness import build_model_for_preset

configs = [
    ("qwen", "Qwen/Qwen3-8B", "https://api.siliconflow.cn/v1/"),
    ("kimi", "moonshot-v1-128k", "https://api.moonshot.ai/v1/"),
    ("deepseek", "deepseek-chat", "https://api.deepseek.com/v1/"),
]

for family_id, model_name, base_url in configs:
    llm = build_model_for_preset(
        model_name=model_name,
        api_key="sk-...",
        base_url=base_url,
    )
    # agent = MyAgent(llm=llm, ...)
    # result = agent.run(task="...", max_steps=20)
```

Each `build_model_for_preset` call resolves the correct protocol, parser, tool delivery, and context policy for that family.

## Step 3 — Override a preset

When a built-in preset does not match your needs, use `preset.override()` to create a customized copy:

```python theme={null}
from dataclasses import replace
from qitos.harness import resolve_family_preset

qwen = resolve_family_preset("qwen")

# Extend Qwen with a larger context window and different stop budget
custom_qwen = qwen.override(
    context_policy=replace(qwen.context_policy, context_window_hint=256_000),
    recommended_max_steps=50,
    notes="Extended context variant for long-horizon tasks",
)
```

The `override()` method returns a new `FamilyPreset` instance — the original is never mutated.

## Step 4 — Explore available presets

Use the CLI to see which presets are available:

```bash theme={null}
qit bench presets
```

This prints a table showing each preset's ID, protocol, tool delivery mode, context window, and recommended models.

You can also list available benchmarks:

```bash theme={null}
qit bench list
```

## Step 5 — Compare runs in qita

After running the same task with different families, launch qita to compare:

```bash theme={null}
qita board --logdir runs
```

In the board view, select two runs and click **Compare** to see:

* which protocol each run used
* the parser and tool delivery mode
* step count, token usage, and cost
* where runs diverged

This makes it easy to see how different presets affect agent behavior on the same task.

## Recommended defaults

Gold presets (Qwen, Kimi, MiniMax, gpt-oss, Gemma 4) include advisory defaults for research baselines:

| Field                      | Default | Meaning                            |
| -------------------------- | ------- | ---------------------------------- |
| `recommended_max_steps`    | 30      | Suggested step budget per run      |
| `recommended_max_tokens`   | 500,000 | Suggested total token budget       |
| `recommended_retry_budget` | 3       | Max critic-retry attempts per step |
| `recommended_temperature`  | 0.2     | Default sampling temperature       |

These are advisory — the engine does not auto-apply them. Use them as starting points for your own experiments.

## The CLI switching pattern

The `examples/real/claude_code_agent.py` example demonstrates the full switching workflow via CLI:

```bash theme={null}
# Qwen
python examples/real/claude_code_agent.py \
  --model-family qwen \
  --model-name Qwen/Qwen3-8B \
  --base-url https://api.siliconflow.cn/v1/

# Kimi
python examples/real/claude_code_agent.py \
  --model-family kimi \
  --model-name kimi-k2-0905-preview \
  --base-url https://api.moonshot.ai/v1

# DeepSeek
python examples/real/claude_code_agent.py \
  --model-family deepseek \
  --model-name deepseek-chat \
  --base-url https://api.deepseek.com/v1
```

Priority order for model configuration:

1. explicit CLI flags
2. environment variables (`QITOS_MODEL_FAMILY`, `QITOS_MODEL`, `OPENAI_BASE_URL`)
3. family preset defaults
4. framework fallback

<CardGroup cols={2}>
  <Card title="Family presets concept" icon="cube" href="/concepts/family-presets">
    Understand what each preset field means
  </Card>

  <Card title="Model family matrix" icon="table" href="/reference/model-family-matrix">
    See all 10 built-in presets and their defaults
  </Card>

  <Card title="Add a family preset" icon="plus" href="/guides/add-a-family-preset">
    Extend QitOS with a new model family
  </Card>

  <Card title="Observability" icon="chart-line" href="/guides/observability">
    Learn how preset metadata appears in traces
  </Card>
</CardGroup>