Fallbacks & reliability

Model providers have outages, rate limits, and occasional bad responses. A fallback model gives a task or agent a second model to fall back to when the primary one fails, so a single provider problem does not take your production runs down with it.

How fallbacks work

Both tasks and agents let you set a fallback model alongside the primary model on their revision:

• Tasks carry fallback_llm_model_id on the task revision.
• Agents carry a fallback model on the agent revision.

When a run’s primary model fails, Rightbrain automatically retries the call on the fallback model. The switch is transparent to the caller — the run continues and returns a result if the fallback succeeds. Failover happens mid-run and preserves progress; it doesn’t restart the run from the top.

The run records that it happened: used_fallback_model flips to true, primary_failure_reason captures why the primary was abandoned, and model_usages carries a per-model split — each model’s call_count, tokens, and credits. A run might show two calls on the primary before it failed and three on the fallback that finished the job, so you can see the failover and what it cost in one record. You are not trading reliability for observability — support sees the failure reason and finance sees the per-model split.

Because the fallback model is part of the revision, it is versioned with everything else. Changing it creates a new revision; rolling back restores the previous pairing. See Versioning & revisions.

Forcing the fallback for testing

You don’t have to wait for a real outage to confirm your fallback behaves. Task runs accept a use_fallback_model query parameter that forces the run onto the fallback model:

$
curl -X POST \
>
  "https://app.rightbrain.ai/api/v1/org/$ORG_ID/project/$PROJECT_ID/task/$TASK_ID/run?use_fallback_model=true" \
>
  -H "Authorization: Bearer $RB_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{ "task_input": { "text": "hello" } }'

Use this to check that your fallback model produces acceptable output before you depend on it in an incident.

Chaos Mode

Forcing the fallback proves one failure path. Chaos Mode lets you rehearse the rest. It injects controlled, deterministic faults into an agent run so you can see how the agent recovers before a real provider has a bad day.

You can inject three kinds of fault:

• Tool errors — make a tool call fail, or return malformed output (an empty result, missing or null fields, unexpected nesting, a truncated or stale payload) so you can test how the agent handles bad tool data, not just missing tools.
• Tool latency — make a tool call slow, to test timeouts and patience.
• Model errors — simulate a model timeout, rate limit, provider outage, or transient internal error.

Two things make it usable in practice. Faults are deterministic: a run carries a seed, so a failure you injected replays identically until you’ve fixed it. And you can target specific tools or whole tool sources (a Task, an MCP server, an integration) rather than breaking everything at once.

Chaos Mode composes with the rest of this page. Inject a “provider unavailable” model error on the primary and you’ll watch the run fail over to the fallback and finish — used_fallback_model: true, with the injected reason recorded as the primary_failure_reason. That’s the whole resilience story exercised end to end, on demand.

Per-model usage split

Runs record how much work each model did, so you can see how often the fallback is actually being used and what it costs. Usage is broken down by model type and by scope:

• Type — primary or fallback. Tells you whether a run leaned on the primary model or fell back.
• Scope — reasoning or memory_compaction. Separates the model’s core reasoning work from the cost of compacting an agent’s memory across a long run.

This split appears in the agent usage reports. A rising share of fallback usage is an early signal that your primary provider is degrading. See Observability & audit for how to read the usage and credit reports.

Retry posture

• Fallback is a model-level retry: primary model fails, the fallback model is tried.
• Timeouts are excluded from fallback — a slow call is not the same as a failed one.
• For transient network errors at the HTTP layer, add your own retry logic in the client calling the Rightbrain API.

Related