---
title: "Models and placement"
description: "Agent definition fields for models and placement."
canonical_url: "https://docs.oz0.ai/reference/agent-definition/models"
---
# Models and placement

> Agent definition fields for models and placement.

For: Plugin authors looking up agent fields.

Look up the fields below when editing an agent definition.

<field-group>
<field name="model.primary" type="string">

The model, as `<provider>/<model>`, for example `anthropic/claude-sonnet-5-5`, or `local/<model>` for a model a node serves. Required unless the runtime is a harness or the agent asks for an alias with `model.use`.

</field>

<field name="model.fallback" type="string[]">

Models tried in order when the primary fails.

</field>

<field name="model.use" type="string">

A model alias of the tenant, such as `smart`, instead of `primary`: each tenant maps it to models of its own providers, and the edge picks one when the job starts ([Models and keys](https://docs.oz0.ai/spend/models-and-keys/aliases#name-the-model-or-ask-for-an-alias)). Every tenant has the [standard aliases](https://docs.oz0.ai/spend/models-and-keys/aliases#the-standard-aliases) `default`, `fast` and `smart`; prefer them.

</field>

<field name="model.needs" type="string[]">

What the alias's model must be able to do: `tools`, `vision`, `structured_output`, `thinking`, `pdf`, `audio`, `web_search`, `prompt_cache`.

</field>

<field name="model.min_context" type="tokens">

The smallest context window the agent works with, such as `128k` or `1m`.

</field>

<field name="model.placement" type="string">

For a `local/<model>`: `node` (the default) sends the agent's jobs to the nodes that serve the model; `fleet` runs them anywhere and sends each model call to the model's queue on the GPU nodes that serve it to the fleet ([local models](https://docs.oz0.ai/fleet/local-models)).

</field>

<field name="model.wait" type="duration">

With `placement: fleet`, how long a model call waits for a slot before it falls back to `model.fallback`; `60s` when unset. An agent with `data: local` never falls back.

</field>

<field name="model.priority" type="integer">

Temporal's priority key, 1 (served first) to 5 (last), for the agent's model calls on the fleet's model queues (`model.placement: fleet`, or a model that resolves to one); unset is 3. See [Local models](https://docs.oz0.ai/fleet/local-models/fleet#share-a-gpu-with-the-fleet).

</field>

<field name="model.cascade" type="string[]">

One to three models, aliases or `<provider>/<model>`, that a failed round restarts on in turn: a round whose answer fails the outcome check (grader, judge, reviewer or verify script) or breaks the output contract after its retries starts again on the next one, as a new conversation with the task, the last answer, the reasons and the earlier tool calls. Provider errors still go to `model.fallback`.

Needs `model.primary` or `model.use` as the first round's model, also for a harness agent, and `outcome` or an output schema; local models only with `data: local`, and every `local/` model in it is required of the job's node; not with `placement: fleet`; refused on `openai-agents` and remote agents (`CascadeUnsupported`). See [A cascade](https://docs.oz0.ai/spend/models-and-keys/effort-and-cascades#a-cascade-the-next-model-only-when-a-round-fails).

</field>

<field name="model.vendor_reason" type="string">

Why the agent names a vendor's model (`model.primary`, a fallback or a cascade step) instead of asking for an alias: the vendor's own feature it needs, in one sentence on one line, at most 300 characters, such as `Runs on the OpenAI Agents SDK, whose hand-offs need an OpenAI model.` Only beside a vendor's model; `local/` and `test/` models need none. `plugin lint --verified` fails a verified plugin's agent that names a vendor's model without it ([OZ-S016](https://docs.oz0.ai/build/plugins/structure/lint-rules#oz-s016)); for other plugins, lint suggests an alias instead, and says nothing once the reason is given.

</field>

<field name="model.effort" type="string">

How hard the agent's model thinks, whichever model the tenant gives it: `low`, `medium`, `high`, `xhigh` or `max`. Unset runs the model at its own default. The tenant's alias may give a target a default, a mapping rule may change it, and the tenant's ceiling may lower it; a level a model lacks is rounded to the nearest one it has, and the job's trace says so (`effort_adjusted`).

It applies to `pydantic-ai`, `openai-agents` and harness agents, and to the agent's judge, fallbacks, cascade steps and best-of candidates; `plugin lint` warns where it does nothing (a remote agent, a `test/` model, a harness that does not say it honours it). A thinking token budget is never set. See [Reasoning effort](https://docs.oz0.ai/spend/models-and-keys/effort-and-cascades#reasoning-effort).

</field>

<field name="requires.labels" type="map">

Labels a node must have to run the agent.

</field>
</field-group>

[Back to the agent definition](https://docs.oz0.ai/reference/agent-definition).


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.