Skip to main content
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. Gold presets (Qwen, Kimi, MiniMax, gpt-oss, Gemma 4) include advisory defaults for research baselines:
FieldDefaultMeaning
recommended_max_steps30Suggested step budget per run
recommended_max_tokens500,000Suggested total token budget
recommended_retry_budget3Max critic-retry attempts per step
recommended_temperature0.2Default 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