# Model selection

The model is the engine behind every agent. The blueprint stores it as a plain
string id; the gateway catalog is what knows whether that id is real and what it
costs. Choosing well is mostly about matching the model's strength to the
agent's actual workload — and not paying for capability the task never uses.

## Pick for the job, not for the headline

The biggest model is not the right default. Reach for a heavyweight model when
the work is genuinely hard reasoning — reviewing a subtle change, weighing
conflicting evidence, planning a multi-step refactor. Reach for a balanced model
when the work is steady and well-scoped: editing files, summarising, answering
straightforward questions. The starter profiles encode this — the reviewer leans
on the heavier model, the coder and researcher on a balanced one — and that is a
good instinct to copy.

## Know the catalog ids

The model id has to be one the gateway recognises. As of this writing the
catalog includes Anthropic ids (`claude-opus-4`, `claude-sonnet-4`,
`claude-haiku-3-5`), OpenAI ids (`gpt-4o`, `gpt-4o-mini`, `o3`, `o4-mini`),
Google ids (`gemini-2.5-pro`, `gemini-2.5-flash`), and a few others. A blueprint
will validate as long as the id is a non-empty string, but the *runtime* adapter
is what checks the id against the registry — so a typo passes the blueprint gate
and fails later. Copy ids from the catalog rather than typing them from memory.

## Spend deliberately

A model that reasons harder usually costs more per token and runs slower. That is
worth it for a reviewer that runs occasionally on important diffs; it is wasteful
for a high-frequency summariser. Think about how often the agent runs and how
much each run matters, then size the model to that. The cheapest correct answer
beats the most expensive one.

## Right-size the smaller jobs

A surprising amount of agent work — classifying, extracting, routing, short
summaries — runs perfectly well on a smaller, faster model. When an agent's task
is narrow and mechanical, a `*-mini` or `*-flash` class id often does the job at
a fraction of the cost and latency. Don't reflexively send simple work to a
flagship model.

## Override, don't fight the profile

When you start from a profile you inherit its model, and most of the time you
should keep it. Override the model only when the agent's workload differs from
the profile's assumptions — for example, a researcher that has to do heavy
synthesis might warrant the heavier model, or a reviewer running on trivial,
high-volume diffs might be fine on a lighter one. Make the override a conscious
choice with a reason behind it, the same way you would for the tool collection.
