Model Selection
Choose for the actual task, not a model’s name or aggregate rank. Prefer the least expensive model that can do the work well enough, and validate important results with tools, tests, and review. For specific benchmark records, read Evals. That page is the dated factual source for external results. This guide explains how to use model evidence without turning benchmark settings into blanket defaults.Automatic subagent and workflow-stage routing
Subagent and workflow-stagemodel: "auto" routes before execution starts, in at most two short requests:
- Questions about the task, answered by a chat model. Kind of work, difficulty, mistake cost, image input, very large context, and whether speed matters. The chat model is
routerModelwhen that is a chat model, otherwise your current one; a classifier such as Jev never reads the task. A task too large for that model’s window is read by the cheapest eligible model that holds it. Anything the caller states intaskNeedsis not asked, and when the caller states all six this request is skipped. Computer-use tasks count as needing images unless the caller says otherwise. - A choice between a shortlist, made by the router without the task. Atomic narrows the eligible models in code: it drops models that cannot read images when the task needs them and prefers 400k-token windows for long-context tasks, then ranks the rest on the Evals results for that kind of work, weighing proven quality against price by how demanding the task is and preferring newer releases. The top six different models form the shortlist; a model’s fast route and the same model on another provider share one place. When the caller lists models in
modelConstraints.allowedModels, those eligible models are the shortlist instead (as many as fit one routing request). Each option carries its own evidence (release date, price tier, image input, and results on this kind of work and overall), ranked against all Evals models however few you enable. With a single option, this request is skipped.
routerModel chooses the decision model only: an explicit registered classifier or chat language model. Unset and auto use the current chat model, regardless of saved classifier credentials. An image-generation model cannot decide.
Only chat language models are eligible for execution auto, including models that accept image or PDF input. Image-generation and classifier models cannot be execution candidates, even when a classifier makes the routing decision.
In authored workflows, a classifier can make a structured triage decision without executing the stage; an image model can generate an asset inside a durable tool step. See classifier and image models in ctx.tool.
To keep providers or models out of routing entirely, set modelRouting.
Benchmarks are evidence, not policy
Benchmark results are measurements under named harnesses, dates, models, efforts, agents, tools, prompts, prices, and scoring rules. Treat a bracketed effort level as the measurement configuration for that row, not a command to run every task at that effort. Compare only records whose measured setup resembles the decision at hand, and keep unmeasured work under ordinary validation rather than inheriting a score. Missing evidence is unknown, not zero. A rounded lead is not proof of significance. A result for one provider, model version, effort, agent, fallback setting, or benchmark harness does not transfer to another identity. Prefer recency. Each row in Evals has a release date. When candidates fit the same role tier and price range, choose the most recently released model over an older one from the same provider or family; a newer release usually supersedes it. Do not let an older model win only because it has no published results: its missing evidence stays unknown, and a recent comparable model with evidence is the safer choice. Recency does not override the role’s cost tier or explicit constraints.Role-based thinking effort
Use these starting defaults unless the user requests a level. Higher effort can improve hard reasoning, but it also costs more and can be slower.max is an exception, not a default.
Price is per task. Candidate cost is USD per million tokens, and roles differ in token volume and in what a mistake costs. High-volume, tool-checked roles such as exploration and routine implementation default to cheaper, faster models; roles where a missed defect is expensive, such as review, verification, and final approval, justify frontier models at high effort. Pick the tier first, then the effort within it; do not compensate for a cheap model with max or for an expensive one with minimal.
An explicit user request wins over these defaults, but the requested level must exist for the selected catalog entry. Do not invent unsupported suffixes. If
xhigh is unavailable, use high rather than automatically promoting to max; choose another catalog model or leave the stage unpinned if neither fits.
Pin model identity from the catalog
Choose only eligible provider/model and effort pairs from the supplied catalog. A guide, benchmark, or outside leaderboard cannot prove that the local account has credentials, quota, region access, tool support, or entitlement. For manual selection, useworkflow({ action: "models" }) or --list-models and pin a returned fullId. Use modelConstraints.allowedModels for hard provider or privacy restrictions. Put softer preferences in the task text.