Fallbacks & reliability | Rightbrain Docs

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.

Task fallback excludes timeout errors. Agent model fallback includes timeout errors. A client disconnect is different: it cancels the live agent execution, so inspect the stored run before retrying it.

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.

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:

Force the fallback model on a task run

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 a fallback proves the alternate model can answer. Chaos testing exercises the surrounding recovery path with bounded, deterministic model and tool faults on a single agent run. Use it to verify failover telemetry, retry policy, malformed-result handling, and latency tolerance before release.

Per-model usage split

Runs record how much work each model did, split by type (primary vs fallback) and scope (reasoning vs memory_compaction — core reasoning versus the cost of compacting an agent’s memory across a long run). The split appears in the agent usage reports; a rising share of fallback usage is an early signal that your primary provider is degrading.

Retry posture

Fallback is a model-level retry: primary model fails, the fallback model is tried.
Task fallback excludes timeouts; agent model fallback includes them.
For an ambiguous HTTP response or disconnect, inspect run status and completed tool actions before retrying. Repeating a run request can create duplicate work.

Choose a fallback model from a different provider than your primary where you can. A fallback on the same provider won’t help you during that provider’s outage.

Observability & audit

Read the per-model usage and credit reports.

Versioning & revisions

Fallback models are part of the versioned revision.

Run tasks via API

Task run options, including use_fallback_model.

Chaos testing

Inject replayable model and tool faults into a test run.

Tasks

Where primary and fallback models are configured.