Skip to main content
Models are described by four objects, in two layers. Getting the layering right is most of the work; after that, pointing an agent at a model is one field. An agent’s model_id is a model instance id. That indirection is the point: you can repoint an instance at a different provider config — a different key, a different endpoint, a proxy — without touching any agent.

​
Prerequisites

  • An access token.
  • An API key for the provider you intend to use.

​
Steps

1

Find the provider spec

This returns providers together with the model specs each one offers, which is usually all you need to pick both ids in one call.
2

Create a provider config

This is where your credential lives. Store the key as a secret rather than inline where your deployment supports it — see pass secrets for the same pattern applied to MCP.
provider_spec_id and name are the only required fields. endpoint_url points at a compatible proxy or self-hosted gateway. Prefer api_key_secret_id, a reference to a stored secret, over an inline api_key.
3

Create a model instance

4

Point the agent at it

Set model_id on the agent to the instance id — at creation, or with a PATCH later. See create and configure an agent.

​
Verify

The test takes the config and spec ids rather than an instance id, so you can check a pairing before you create an instance for it. A failure here is a credential or endpoint problem, and it is much easier to read than the same failure surfacing mid-task.

​
What the model spec controls at runtime

Two fields do more than describe:
  • context_window seeds context management and compaction. It has no default — a task whose model declares no positive window fails at startup with InvalidExecutionSnapshot rather than running against a guess.
  • default_context_strategy sets the per-model default of static, hybrid or dynamic, which an agent may override.
Per-token costs drive budget accounting. Every paid call is metered, including context compaction, and a call that returns no token usage is an error rather than a free call.

​
Troubleshooting

The agent runs but always uses the wrong model. Check the agent’s model_id rather than the provider config — several instances can share one config. Changing a provider key did not take effect. The workflow resolves the model once at task start and caches it for the run. In-flight tasks keep the old resolution; new tasks pick up the change. A running task can be moved with the change_model command.

Create and configure an agent

Create an agent, bind it to a model instance, and give it instructions and tools

Context strategies

Three settings — static, hybrid and dynamic — decide whether large tool outputs are offloaded to

Set a budget

Cap monthly spend, per-run spend, service spend or tokens for a workspace, agent, user or single
Last modified on September 17, 2026