The default for new agents
When an agent is created, Formation gives it a first routing policy from the installation’s new-agent default. Out of the box that default is on, with familyany and preference balanced; an installation owner can change the
preference or turn the default off (PUT /api/settings/model-routing with
new_agents, below). The default only affects agents created afterwards:
existing agents keep their policy, and an agent with no saved policy keeps
automatic selection off.
The new agent still needs a concrete primary model — the setup wizard asks
for one, and instance defaults can supply one. Under family any — the only
family a new agent starts with — or any family that includes the primary, the
primary is the conservative fallback and the price ceiling: selection never
picks a model whose input or output token rate exceeds the primary’s, and the
primary answers whenever selection cannot choose. (An owner who restricts an
agent to a family that excludes its primary gets the best eligible model in
that family as fallback and ceiling instead; see
Fallbacks and run recovery.) Fast and heartbeat
roles are optional (an unset role inherits the primary) and are not routed.
A seeded policy needs nothing else to be configured before turns can be served.
Until the agent has a usable primary, selection steps aside and the turn is
served on the primary exactly as if automatic selection were off — no route is
recorded and no classification is spent. Selection steps aside when:
- no concrete primary is configured (the provider’s router default, such as
openrouter/auto, is never a fallback); - the connection’s catalog does not list the primary;
- the primary is not eligible for the request — for example its context window is smaller than the agent’s prompt allowance (128K input tokens by default, plus the reply), or it declares no tool support while tools are offered.
any and
owners restrict a family per agent.
Change automatic selection for an agent
Open the agent’s Models page:- Configure a working provider connection and a concrete primary model. Keep a primary model suitable for the hardest work this agent should handle.
- In Automatic model selection, choose a model family and preference.
- Turn Choose models automatically on or off and select Save model selection. Turning it off never requires a working connection.
auto), an
agent on OpenRouter classifies through the same credential that serves its turns
(its own key, or the instance key it inherits); an agent on a provider without a
native decision route keeps its primary unless the installation configures an
explicit decision provider.
Saved changes apply to new turns. Manual primary, fast, and heartbeat settings
are retained; turning automatic selection off restores the manual path. Under
Evaluation options, Collect shadow decisions using the current answer
model records routing choices without changing the answer model. Shadow mode
can incur classification charges and cannot be enabled alongside live selection.
How Formation chooses
Formation discovers the catalog through the agent’s resolved provider, endpoint, and credential. It keeps a snapshot of at most 32 candidates, preserving configured roles and family diversity. Snapshots expire after ten minutes and refresh automatically. Connection changes invalidate cached facts. The Decision model classifies the request into a complexity level: simple, standard, advanced, or frontier. Runtime code then maps that classification to eligible models. The selection step does not generate an answer or invoke a serving text model. For the current catalog-based path, price is a ranking proxy, not measured model quality. Candidates are ordered into price tiers. Automatic selection excludes candidates whose input or output token rate exceeds the conservative fallback’s corresponding rate. Frontier work reaches the fallback at the top of the ladder. The configured primary is the fallback when it remains eligible; a family or capability restriction can require another eligible fallback.
Catalogs with only model IDs and no comparable prices cannot establish a useful
price ladder. Formation keeps the fallback in that case. Where output-modality facts
are absent, discovery includes only configured primary/fast roles instead of
assuming every returned ID can generate text.
These preferences are selection rules. They do not establish measured speed,
quality, or total-cost improvements for your workload, and they are not a
monetary spending limit.
Fallbacks and run recovery
The selection phase has a two-second budget and runs concurrently with tool preselection. An uncertain or low-probability classification, Decision failure, timeout, saturation, incomplete context, installation routing stop, or a single eligible model keeps the conservative fallback. If catalog discovery fails, the serving path can fall back only to the configured concrete primary, with a 30-second catalog retry backoff; without a concrete primary it steps aside to the manual path (above). Cancellation and storage failures still propagate. Routing never makes a smaller model fit by discarding extra evidence. With familyany, a request the primary itself cannot serve is left to the manual path,
which admits it against the primary exactly as with routing off. Under an
explicit family that excludes the primary, the fallback is the best eligible
model in that family, and if no model in it is eligible, selection fails instead
of ignoring the family. There is no mid-run plan-to-execution model switch.
Scheduled instructions retain their existing model path.
A routed turn’s provider-failure fallback is the fallback recorded in its route
(selection.fallback: the primary, except under a family that excludes it);
MESH_MODEL_FALLBACK_MODELS applies to turns without a captured route.
A captured selection belongs to its run. Recovery reuses that choice without
classifying again, after checking current connection binding, catalog membership,
and capability requirements. A revoked or incompatible choice cannot silently
resume on a different model.
Inspect and control routing
Routing details belong in the operator trace, not in normal conversation. Formation records the policy, catalog snapshot, candidate exclusions, selected model, classification, and native Decision call ID. Useful operator endpoints are:
The stop switch preserves captured runs. Disable an individual agent’s routing
policy to return new turns to manual model selection. Stale policy edits return
409 and require a refresh. A hosting control plane holding the management
credential can read and change an agent’s policy and read the installation
document (capability
models.routing); the stop switch and the new-agent
default stay owner-only. Policy writes are recorded in the activity log.
Automatic selection is not a provider router alias. openrouter/auto and other
router pseudo-models remain refused as model settings (roadmap risk R11):
Formation selects a concrete, pinned model per run and
records which one, its candidates and the classification, so cost and
behaviour stay attributable and a recovered run resumes on the same model.
The decision_calls ledger records model_routing classification and each
model_routing_attempt serving attempt. Successful serving calls also appear in
model_calls; do not add both records’ token counts when calculating usage.
Audit-write failure blocks inference or use of the result. Body retention follows
the existing operator retention settings.
The legacy reviewed-profile API remains available for compatibility and has its
own qualification rules. Publishing a profile is not part of normal catalog-based
setup. The implementation is in internal/modelrouting, with serving wiring in
internal/app/model_routing.go and internal/turn/model_routing.go.