> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formation.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Automatic model selection

> Choose answer models per turn using provider catalogs and bounded complexity decisions.

Automatic model selection lets Formation choose a concrete answer model for each new
conversational run. It uses the agent's existing provider connection, available
models, and request complexity. The agent keeps the same identity, persona,
memory permissions, and tools when the model changes.

Automatic selection is **on by default for new agents** (any family, balanced
preference) and stays off for agents created before that default existed. It
does not require an uploaded evaluation profile or a separate installation
serving credential.

## 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
family `any` 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](#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.

If catalog discovery fails (no credential yet, provider unavailable), serving
uses a catalog containing only the primary, so the turn is answered on the
primary and discovery is retried after 30 seconds.

A turn incurs a decision-model classification charge only when selection
actually classifies: more than one eligible model, a usable native Decision
route, and none of the skip conditions (installation stop, incomplete context,
run recovery, saturation). Then it makes one bounded classification (below) on
the agent's provider credential, in exchange for routing simple requests to
cheaper models. Otherwise the route keeps its fallback without classifying,
and a turn selection steps aside from makes no route at all.

New-agent defaults never carry a model family. A family is a hard filter that a
per-agent save checks against that agent's own catalog; a policy seeded before
the agent has a provider could not be checked, so seeded policies use `any` and
owners restrict a family per agent.

## Change automatic selection for an agent

Open the agent's **Models** page:

1. Configure a working provider connection and a concrete primary model. Keep a
   primary model suitable for the hardest work this agent should handle.
2. In **Automatic model selection**, choose a model family and preference.
3. Turn **Choose models automatically** on or off and select **Save model
   selection**. Turning it off never requires a working connection.

Available families come from that agent's provider catalog: any available family,
Anthropic, OpenAI, Google, or xAI. Family is a hard filter. A model also needs to
fit the request's known context, output, tool, and image requirements.

A native [Decision model](/runtime/decision-models.md) is needed for complexity-based
selection. If the installation has no native Decision route for this agent,
automatic selection keeps its conservative fallback. It does not ask the fast
text model to choose a model. Under the default decision setting (`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.

| Preference | Current catalog behavior |
| - | - |
| Balanced | Map complexity to the corresponding price tier. |
| Faster responses | Use the same tier mapping as Balanced; the catalog path does not rank measured latency. |
| Lower cost | Bias the mapped choice one tier cheaper, within the eligible pool. |
| Best quality | Bias one tier higher, capped at the 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 family
`any`, 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:

| Endpoint | Purpose |
| - | - |
| `GET/PUT /api/agents/{slug}/model-routing` | Inspect or change the agent's routing policy. Writes include the last observed revision. |
| `GET /api/agents/{slug}/model-routes?before={run_id}` | Page through captured routes, 50 per page. |
| `GET /api/settings/model-routing` | The installation document: `{"stopped":false,"new_agents":{"enabled":true,"preference":"balanced"}}`. |
| `PUT /api/settings/model-routing` with `{"stopped":true}` | Installation-owner stop: skip new classification and use the eligible fallback. |
| `PUT /api/settings/model-routing` with `{"new_agents":{"enabled":false}}` | Installation-owner change to the new-agent default (`enabled`, `preference`; omitted fields are kept). Affects agents created afterwards only. |

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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.