Choose models

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.

At a glance

• 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

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.

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.

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.

Changing the model list is a new version

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: what else the version contract carries.
• Policy, approvals, and evidence: where the model decision sits among the other ceilings.
• Agent manifest: the field reference.