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:

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:

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:

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:

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:

qit bench list

Step 5 — Compare runs in qita

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

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:

# 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

Family presets concept

Understand what each preset field means

Model family matrix

See all 10 built-in presets and their defaults

Add a family preset

Extend QitOS with a new model family

Observability

Learn how preset metadata appears in traces