The end state
When the recipe is done:- The new model has a row in the model catalog with pricing, capabilities, and lifecycle status.
- The agent’s
model.defaultnames the new catalog model. Already-started turns retain their resolved configuration; later dispatches resolve again. - A virtual key is configured (if the new model is from a new provider) so the secrets store capability resolves credentials at dispatch time, not at boot time.
- Every dispatch records its actual model in
stepResults.modelUsed; the swap itself records toauditEventswith the worker who made the change.
Prerequisites
- The agent whose model you are changing, and an active row in the model catalog for the model you are switching to (step 1 registers it if it is absent).
- A virtual key for the new model’s provider, if that provider is not yet in the secrets store (step 2).
- For the API path: the
FORGE_BASEandACCESS_TOKENfrom the Raw HTTP tab of the quickstart, withagents:read, andagents:writeat the agent’s home. An External App token changes only agents that app owns; a Personal key or platform API key sends the change inside apatchobject.
The four steps
1
Register the model
The model catalog is the platform’s source of truth for available models, lifecycle, capabilities, routing metadata, and pricing. Prefer an existing active row. If the model is absent, register it through the supported model-catalog operator surface and verify the saved row before changing an agent. The exact write contract is documented by that surface; do not paste a speculative database row into production.Record the catalog model ID you selected, confirm it supports the tools and context window this agent needs, and note its active provider chain. The ID is the value used in
model.default; the observed model on a run is evidence of what routing ultimately selected.2
Wire the virtual key (if needed)
If the model is from a provider already in the secrets store capability, skip this step. If it is from a new provider, configure a virtual key so the dispatch resolver can fetch credentials without leaking them into agent definitions.The recipe for adding a new vendor adapter is in Capabilities. For a new model from an existing provider, the work is one entry in The agent never holds the key; it asks the resolver for the model and the resolver asks the secrets store at dispatch time. That indirection is what makes “swap the underlying provider” a config change rather than a code change — see the capability resolution section for the full pattern.
deploymentConfig.capabilities.secrets_store.options — a key reference that maps to whichever store the workspace runs (1Password, internal, env-only).3
Swap the preference
Edit the agent’s model configuration through Workforce → Agents → [agent] → Edit. The persisted field is Agent composition resolves the model for each dispatch. A turn that already resolved its model is not rewritten; the next eligible dispatch reads the new active definition version. Save the change as a new agent version and verify that version is active before launching the canary.If you want to validate the swap on a smaller surface first, point one workflow at the new model by overriding at the node level. Workflow node config can pin a specific model that wins over the agent’s preference; pin one node, run a few times, then promote the change to the agent definition.
model.default; model.allowOverride controls whether a caller may override it:4
Verify the swap landed
The trace says what actually ran. Open a recent run in the Console (or read it with
GET /api/v3/runs/{runId}, which needs runs:read) and read each step’s model in steps. The runs that started before the swap should show the old key; the runs that started after should show the new key. If the model recorded does not match what you expected, the resolver got something different than the preference — usually a workflow-level model override or a per-node pin. See Execution Traces for the full record.Do it over the API
These calls use theFORGE_BASE and ACCESS_TOKEN set up in the Raw HTTP tab of the quickstart.
Confirm the new model has an active catalog row, which needs agents:read:
agents:write at the agent’s home, and only the fields you send change. With the quickstart’s External App token the call patches an agent that app owns. A Personal key or platform API key sends the same fields inside a patch object, {"patch": {"model": {…}}}.
Confirm which version is now active, which needs agents:read:
forge_call_operation runs the swap as updateAgent on a connection made with External App credentials. A host signed in with a Personal key uses updateAgentAdmin, which takes the change as a patch:
forge_call_read_operation lists the versions:
When to reach for something else
- The new model is not yet in the catalog and you need it for one experimental run. Don’t register it. Use a workflow-node-level model pin against the existing catalog model that has the closest pricing/capabilities; promote to a real catalog row once the experiment proves out.
- You want different agents to use different models for different tasks. Don’t manage the choice as a per-agent preference — that scales poorly. Use the tier-based routing described in LLM routing: the agent declares the kind of work (cheap classification, heavy reasoning) and the platform resolves that tier to a concrete model at dispatch time.
- You want to A/B test two models on the same agent. Use a
routernode in the workflow that splits 50/50, with each branch pinning a different model. ComparestepResults.costandmodelUsedin aggregate; promote the winner. - You’re mid-incident and need to fail away from a model that’s degrading. Don’t edit the catalog — that’s a config change you’ll regret on Friday. Runtime failover comes from the agent’s model fallback chain (
fallbackChainId): when a call to one model fails, the chain tries the next. Give the agent a chain before the incident, not during it. A model that is degrading but still answering keeps getting traffic, because the chain starts at its first entry, and changing the agent’smodel.defaultdoes not change that. Either move the standby to the top of the chain on Platform → Fallback Chains (this applies to every agent on that chain), or pin the standby on the affected workflow node, which bypasses the chain. Undo the change when the upstream provider recovers.

