How do I choose a model?

Stackbone does not rank models for you. It gives you one place to set each model, a live catalogue to read, and eval suites to measure a swap once you have made it.

Three model ids come from your own project, and you set each one in a different place. The agent's reasoning model is the model you pass to defineDeepAgent(...) in its index.ts. It drives the main loop. A one-off completion, embedding or image goes through stackbone.ai, where you pass model on the call itself. Retrieval takes the model you pass on the stackbone.rag call. The rag.embeddingModel key in agent.yaml parses but changes nothing. Guardrails, evals and the built-in workflows use their own models, and you pick those in Studio settings rather than in code.

An id in the code is a default, not the last word

An operator can pick another model for an agent, for one of its subagents, or for a model key your code names, on the entry's Models block in Studio. That pick outranks the id in the code and needs no redeploy. Four sources are tried in order:

#	Source	Set by
1	The model picked in Studio	An operator, on the entry's Models block.
2	The id written in the code	You.
3	The workspace's Default model	An operator, under Settings › Workspace.
4	Nothing resolves, so the run fails	Nobody. This is the no_model_configured case.

So model on defineDeepAgent(...) is optional: leave it out when the agent must run in deployments whose providers serve different ids. For a workflow, name a key with stackbone.models.use(key) and the same order applies to it. When nothing names a model, the run fails with no_model_configured, which you fix with a pick in Studio, an id in the code, or a workspace default model.

To compare candidates, read the catalogue. stackbone.ai.models.list() returns whatever the provider reports for each model, which on OpenRouter includes context_length and pricing. Every id uses the creator/model-name form, so switching is a one-line edit.

Then measure the change. An eval suite runs your saved cases against the agent and reports a pass rate against a pass mark. Run the suite in CI.

Read more

• Gateway: where each of those ids is set, and the one endpoint they all resolve through.
• stackbone.ai: the catalogue call and every ai_* error code.
• stackbone.models: the resolution order in full, the Models block in Studio, and the no_model_configured error.
• Testing and evals: how to measure a model swap.
• Which models can I use?: providers and the ids they resolve.