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

# Agent model selection

> How Orbit picks the LLM for an agent: the per-agent model field, the platform default, and the resolution order behind it.

# Agent model selection

Every agent run picks exactly one model. You control it per agent with the `model` field; when you omit that field the agent uses the **platform default model**. This page explains both paths and the resolution order the platform follows so you can predict — and pin — which model a tenant's agents run on.

## Set the model per agent

Pass `model` on create or update. Agent runs route through Anthropic only, and the API accepts a fixed allowlist of Claude model ids rather than every id Anthropic currently serves. The supported ids are:

| Model id                    | Tier                                                                                                                                                                                                                                             |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `claude-opus-4-7`           | Deepest reasoning, and the vision-capable tier for agents that take image input; orchestration, compliance, and billing agents                                                                                                                   |
| `claude-sonnet-4-6`         | General-purpose tool worker                                                                                                                                                                                                                      |
| `claude-haiku-4-5-20251001` | Fast triage and classification                                                                                                                                                                                                                   |
| `claude-fable-5`            | Premium vision tier (image and PDF input). Temporarily unavailable (export-suspended): the id is accepted on create and update, but requests pinned to it fall back to `claude-opus-4-7` until the suspension lifts — see the status note below. |

Send the id exactly as listed, including the dated snapshot: `claude-haiku-4-5-20251001` is accepted, but the bare alias `claude-haiku-4-5` is not. Any id outside this list is rejected at the write boundary with a `422` and the `error.code` `INVALID_MODEL` — see [When a model id is rejected](#when-a-model-id-is-rejected) below. That includes a Claude model Anthropic has released but Orbit has not yet added: a new Anthropic release is not accepted automatically. Orbit adds support for each id before an agent can pin it, so treat the four ids above as the current set. Call `GET /api/v1/agents/models` for the live, authoritative list of **currently selectable** ids, or check back here when you need a newer model.

<Note>
  `GET /api/v1/agents/models` returns only the ids you can newly select, so while a model is export-suspended it is a strict subset of the table above. `claude-fable-5` is the current example: it stays in this table because create and update still accept it (requests pinned to it fall back to `claude-opus-4-7`) and agents already pinned to it keep running, but because you cannot newly select a suspended id it is omitted from the endpoint response until the suspension lifts. If an id appears in this table but not in the endpoint response, check whether the table marks it export-suspended.
</Note>

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/agents \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "model": "claude-sonnet-4-6",
    "system_prompt": "You are a customer support agent for Acme Corp."
  }'
```

If you leave `model` unset, the agent resolves to the platform default at run time — you are never required to pin a model per agent.

## When a model id is rejected

Every path that writes an agent rejects a `model` outside the supported list, and all three write boundaries return the same error code on the `422` — `INVALID_MODEL`. One branch on `error.code` covers every path:

| You send an unsupported `model` to…                                     | Status | `error.code`    | What you get back                                                                                                                                                                  |
| ----------------------------------------------------------------------- | ------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/v1/agents` (create) or `PUT /api/v1/agents/{id}` (update)    | `422`  | `INVALID_MODEL` | The message names the id you sent and lists the accepted ids. On update, a genuine model *change* is validated; re-submitting an already-persisted id you are not changing is not. |
| `POST /api/v1/agents/config/import` (import a portable config document) | `422`  | `INVALID_MODEL` | The `agent.model` field in the imported document was not a supported id.                                                                                                           |

Every path carries HTTP `422` and `error.code` `INVALID_MODEL` in the standard [error envelope](/api-reference/error-codes), so a single branch on `error.code === 'INVALID_MODEL'` handles a rejected model id from create, update, or config import. An id Anthropic has released but Orbit has not yet added is rejected the same way; a new Anthropic release is not accepted automatically.

## The platform default

The platform default is the model an agent uses when its own `model` field is unset. It is resolved fresh by the agent runtime, in this order:

1. **Admin pin.** If a platform admin has pinned a model, that id wins and auto-discovery is bypassed. Use this to hold every tenant on a known-good model when a new release breaks a flow.
2. **Auto-discovery.** Otherwise the runtime queries Anthropic for the available models, selects the newest in the default agent family, and caches the result for 24 hours. When Anthropic ships a newer model in that family, every tenant flows onto it within 24 hours of the next agent run — no redeploy. (This path is paused today — see the status note below.)
3. **Boot fallback.** If Anthropic's model listing is unreachable and no admin pin is set, the runtime falls back to a configured boot default (see below).

Discovery never returns an id the provider does not serve, so a tenant agent always resolves to a live model.

<Note>
  **Current status.** The default agent family is Fable, but Anthropic's Fable models are export-suspended: they still appear in the model listing, yet completions against them return a 404. Auto-discovery skips any suspended id, so the Fable step currently returns nothing and resolution falls through to the Opus fallback. **Every tenant runs on `claude-opus-4-7` today.** The auto-discovery-onto-the-newest-Fable behaviour described above is the design for normal operation and resumes automatically once the suspension lifts — no redeploy. To hold tenants on a specific model in the meantime, set an admin pin (`model.tenant_default`).
</Note>

## Platform-default configuration (operators)

These settings are owned by platform operators, not tenants. They are documented in full in the [agent default model runbook](https://github.com/devotel/orbit/blob/main/infrastructure/runbooks/agent-default-model.md).

| Variable                       | Default           | Role                                                                                                                                                                                                                                 |
| ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DEVOTEL_TENANT_DEFAULT_MODEL` | `claude-opus-4-7` | Boot fallback for the tenant default model — used only when Anthropic's model listing is unreachable and no admin pin is set. Pin the platform-wide default here.                                                                    |
| `DEVOTEL_DEFAULT_AGENT_MODEL`  | *(unset)*         | **Deprecated alias** of `DEVOTEL_TENANT_DEFAULT_MODEL`. Honoured only during cutover, and only when it holds a `claude-` id; a non-Claude value is ignored. Migrate any pin onto `DEVOTEL_TENANT_DEFAULT_MODEL` and retire this var. |

<Note>
  `claude-opus-4-7` is the current live Opus boot fallback. It takes effect when both the admin pin and auto-discovery are unavailable — and because Fable-family discovery is currently export-suspended (see the status note above), the Opus branch is the path every tenant is on today. When the suspension lifts, auto-discovery selects the newest model in the default agent family again. If you need a tenant to stay on a specific model regardless of discovery, set an explicit admin pin (`model.tenant_default`) rather than relying on the boot fallback.
</Note>

To override auto-discovery without a redeploy, a platform admin pins the default in platform config rather than changing the boot fallback. The boot fallback only takes effect when both the admin pin and live discovery are unavailable.