> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Replace a model on a live agent

> End-to-end recipe — register a new model in the catalog, swap an active agent's preferred model, and roll the change to production with no in-flight runs lost and full audit of the swap itself.

The model an agent uses is a piece of configuration, not a piece of code. Forge separates the model catalog (what the platform knows about) from the agent's preference (which model an agent reaches for) from the dispatch resolver (what actually runs at this moment). That separation is what makes a zero-downtime swap a configuration edit rather than a deploy.

## The end state

When the recipe is done:

* The new model has a row in the [model catalog](https://docs.gloo.com/forge/build/define-an-agent.md) with pricing, capabilities, and lifecycle status.
* The agent's `model.default` names 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](https://docs.gloo.com/forge/concepts/capabilities.md) resolves credentials at dispatch time, not at boot time.
* Every dispatch records its actual model in [`stepResults.modelUsed`](https://docs.gloo.com/forge/run/observability); the swap itself records to [`auditEvents`](https://docs.gloo.com/forge/run/audit) with 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_BASE` and `ACCESS_TOKEN` from the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md), with `agents:read`, and `agents:write` at 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 a `patch` object.

## The four steps

REPLACE A MODEL ON A LIVE AGENT

<ol aria-label="REPLACE A MODEL ON A LIVE AGENT" />

**1. Register the model**

The [model catalog](https://docs.gloo.com/forge/build/define-an-agent.md) 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](https://docs.gloo.com/forge/concepts/capabilities.md), 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](https://docs.gloo.com/forge/concepts/capabilities.md). For a new model from an existing provider, the work is one entry in `deploymentConfig.capabilities.secrets_store.options` — a key reference that maps to whichever store the workspace runs (1Password, internal, env-only).

```yaml theme={null}
# deploymentConfig.capabilities.secrets_store
{
  "providers": ["one_password"],
  "options": { "vault": "forge-prod" },
}
```

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](https://docs.gloo.com/forge/concepts/capabilities.md#how-resolution-works) for the full pattern.

**3. Swap the preference**

Edit the agent's model configuration through **Workforce → Agents → \[agent] → Edit**. The persisted field is `model.default`; `model.allowOverride` controls whether a caller may override it:

```diff theme={null}
- model: { default: "anthropic/claude-opus-4-7", allowOverride: false }
+ model: { default: "anthropic/claude-haiku-5", allowOverride: false }
```

[Agent composition](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-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.

**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](https://docs.gloo.com/forge/run/observability.md) for the full record.

## Do it over the API

These calls use the `FORGE_BASE` and `ACCESS_TOKEN` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md).

Confirm the new model has an active catalog row, which needs `agents:read`:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/models?status=active&search=haiku" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | {modelId, provider, contextWindow, status}'
```

Swap the agent's default model:

```bash theme={null}
curl -sS -X PATCH "$FORGE_BASE/api/v3/agents/$AGENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $AGENT_ID-model-haiku-5-v1" \
  -d '{"model": {"default": "anthropic/claude-haiku-5", "allowOverride": false}}' \
  | jq '.data'
```

This needs `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`:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/agents/$AGENT_ID/versions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | {versionId, version, status, active, canary, createdAt}'
```

Over MCP, `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`:

```json theme={null}
{ "operationId": "updateAgentAdmin", "idempotencyKey": "swap-model-v1", "input": { "agentId": "<agent slug>", "patch": { "model": { "default": "<new model id>" } } } }
```

On an External App connection:

```json theme={null}
{
  "operationId": "updateAgent",
  "input": { "id": "<agent slug>", "model": { "default": "anthropic/claude-haiku-5", "allowOverride": false } },
  "idempotencyKey": "<agent slug>-model-haiku-5-v1"
}
```

`forge_call_read_operation` lists the versions:

```json theme={null}
{ "operationId": "listAgentVersions", "input": { "id": "<agent slug>" } }
```

## 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](https://docs.gloo.com/forge/architecture/llm-routing.md#five-tiers): 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 `router` node in the workflow that splits 50/50, with each branch pinning a different model. Compare `stepResults.cost` and `modelUsed` in 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](https://docs.gloo.com/forge/console/platform/fallback-chains.md) (`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's `model.default` does 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.

Forge keeps the catalog (what exists), agent configuration (the default and override posture), and dispatch resolution (what actually runs) separate, so a model change never touches application code; see [Composable capabilities](https://docs.gloo.com/forge/concepts/capabilities.md) and [LLM Routing](https://docs.gloo.com/forge/architecture/llm-routing.md) for provider and tier-based resolution.

**A model swap that requires a deploy is not a swap — it is a release.**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.