# Choose models

Declare the model an agent uses and the models a run may request, and understand what the tenant's LLM gateway does with every call.

An agent never talks to a model provider directly. Every model call leaves the sandbox through the
tenant's LLM gateway, which is where model access is authorized, usage is metered per run, and
traffic is traced. Your manifest declares which models the agent may use; the gateway enforces it.

- `model` is the default the agent runs with. `permitted_models` is the allowlist a run may
  choose from.
- A run that requests a model outside the allowlist is refused at the gateway.
- Model IDs are the ones available to your tenant. The same manifest can deploy to tenants with
  different model lineups only if the IDs exist in each.
- Usage is metered per run, so cost and spend are attributable to a session, a run, and the
  principal that started it.

## Declare the models

```yaml title="agent.yaml"
model: "your-workspace-model-id"
permitted_models:
  - "your-workspace-model-id"
  - "your-workspace-fast-model-id"
policy:
  scope_ceiling:
    - "llm:your-model-family:invoke"
```

- **`model`** is resolved for a run unless the request overrides it.
- **`permitted_models`** bounds overrides. Leaving it empty does not widen access: it means the
  manifest declares no allowlist and the decision falls to platform and tenant policy.
- **`policy.scope_ceiling`** must carry the `llm:<family>:invoke` entry for the model family the
  agent calls. Change the model, update the ceiling, or the declared ceiling stops describing what
  the agent does.

## Follow the organization default

Set `model: default` to run on your organization's default model, chosen on the Console's
Models page (or with `tanomis model default set`). The default can be any active model on that
page: one of your organization's own models or one of the platform's. Until the organization
chooses one, `default` is the platform default. Each new session resolves `default` to the model
it points at then, so changing the default moves every agent that follows it without a new
version; open sessions keep the model they started with. If the chosen model stops being
available, sessions that follow the default are refused with the reason, and the Models page
warns, until someone chooses again. A concrete model ID pins the agent to that model, whatever the
default is.

```yaml title="agent.yaml"
model: default
permitted_models:
  - default
```

`permitted_models` may list `default` alongside concrete IDs; it admits the one model the default
resolves to for the session. `tanomis agent new` scaffolds `model: default` for the Claude harness.

## Override per session or run

A session can be created with a `model` from the permitted set, and a run can request one the
same way. An override outside the set is a `400` at request time, before any work starts.

```json title="POST /v1/sessions"
{ "agent_name": "support-copilot", "model": "your-workspace-fast-model-id" }
```

## What the gateway does with a call

| Concern | What happens at the gateway |
|---|---|
| Authorization | The model is checked against the version's allowlist and tenant policy. A refusal is a policy decision recorded in the audit trail. |
| Metering | Tokens and requests are attributed to the run, so spend rolls up to sessions, agents, and principals. |
| Tracing | Each call becomes a span in the run's execution trace, on the tenant's own trace plane. |
| Isolation | The gateway is per tenant. Traffic from one tenant never shares a gateway with another. |

You do not configure the gateway. It is provisioned with the tenant; the manifest is the only
input you control.

## Choose between models

A single agent can hold a capable default and a faster, cheaper model in its allowlist, and let
the calling application pick per request. Keep the allowlist short: every entry is a model the
agent is authorized to call, and the ceiling entry must cover its family.

`model` and `permitted_models` are part of the version's contract. To add a model, deploy a new
version and roll it out; a running version's list never changes.

## Where to go next

- [Agents and versions](/concepts/agents-and-versions): what else the version contract carries.
- [Policy, approvals, and evidence](/concepts/governance): where the model decision sits among
  the other ceilings.
- [Agent manifest](/reference/agent-manifest#models): the field reference.