<!-- source: https://docs.dreamlake.ai/agents/models @ 0.1.192 b2f973b1 -->
# Choose an agent model

Use the **Default** menu in the built-in agent's composer to choose a model for
that conversation. The menu lists the models configured by your DreamLake
operator. Your choice is saved when you send a message and restored when you
reopen the conversation. New conversations start with Default.

**Default** keeps the existing routing: ordinary turns use the general model;
a research agent uses the configured research model when one is provided.
Selecting a named model overrides that routing for future turns in this
conversation. The selector is disabled while a response is running or a
conversation is restoring. Changing models preserves your draft and history.

The transcript shows **Model: …** when the provider reports which model answered.
If that identifier differs from the requested route, the notice includes both.
These notices remain visible after reopening the conversation. An older answer
or a provider response without model metadata may have no model notice; the
selected name alone does not verify which model ran.

## Availability and recovery

An unavailable or removed model produces an error. Your choice is kept; the
agent does not retry with another model. Choose a different model or explicitly
choose **Default**, then send again. If the catalog cannot load, reopen the menu
to retry. A configured choice does not guarantee upstream availability.

Model selection does not change the conversation's namespace, tool permissions,
connected-app consent, research steps, or context limits. Codex and Claude
terminal-session settings are separate from this built-in agent menu.

## API contract

`GET /agent/models` requires sign-in and the same agent access as chat. It performs
no inference or provisioning and returns:

- `version: 1`, `defaultModel`, and `researchModel`.
- `models`: unique configured routes with `id`, `label`, and `available`.

`available` means a server provider credential is configured; it is not a live
provider probe. The allowlist comes from `BUILTIN_AGENT_MODEL` and
`BUILTIN_RESEARCH_MODEL`, with the existing general default when unset.

`POST /agent/chat` accepts an optional `model` field:

| Value | Behavior |
| --- | --- |
| A configured model ID | Use it and save the choice with the admitted turn. |
| `null` | Explicitly restore Default routing. |
| Omitted | Preserve the saved choice, or Default for a new conversation. |

The existing conversation lease rejects competing turns before they can change
its choice. `agent_model_not_allowed` rejects unknown or removed selections;
`agent_model_unavailable` reports a provider refusal. Neither triggers a different
model. The configured research-provider restriction follows its research model;
selecting the general model does not pin it to the research model's provider.
Explicit selections require parameter support; tool execution stays sequential.

The initial SSE `context` event includes `model` and the resolved `requestedModel`.
A `model` event contains `turnId`, `requested`, `actual`, and `ts` when the provider
reports a safe identifier. `GET /agent/sessions/:id` returns the saved `model` and
these `modelRuns` receipts. Receipts are display metadata and are not inserted
into model history.

The delegated read-only assistant/MCP adapter cannot set `model`. There is no new
CLI or Python SDK chat command for this selector.
