Step fallbacks

Step fallbacks route a failed primary step to a backup step instead of failing the entire workflow immediately. You set fallback_step_id on a StepDefinition to point at another step id in the same workflow. When the primary agent fails in a way that triggers fallback, the engine activates the fallback step and emits StepFallbackActivated in the trace.

Fallbacks complement Retry and backoff: retry handles transient provider errors; fallback handles "try a cheaper model" or "escalate to a specialist agent" patterns after primary failure or alongside retry exhaustion.

When to use fallbacks

Fallback is not a substitute for Graph workflows routing. It activates on step failure, not on conditional output.

Workflow configuration

{
 "id": "00000000-0000-4000-8000-000000000001",
 "name": "resilient_qa",
 "execution_mode": "linear",
 "steps": [
 {
 "id": "00000000-0000-4000-8000-000000000010",
 "agent_id": "00000000-0000-4000-8000-000000000020",
 "order": 1,
 "fallback_step_id": "00000000-0000-4000-8000-000000000012"
 },
 {
 "id": "00000000-0000-4000-8000-000000000011",
 "agent_id": "00000000-0000-4000-8000-000000000021",
 "order": 2,
 "fallback_step_id": null
 },
 {
 "id": "00000000-0000-4000-8000-000000000012",
 "agent_id": "00000000-0000-4000-8000-000000000022",
 "order": 3,
 "fallback_step_id": null
 }
 ]
}

In this layout, step 010 primary agent 020 falls back to step 012 (agent 022) on qualifying failure. Step 011 has no fallback. The fallback step's order value still participates in linear sort when the fallback path is not taken; when fallback activates, the engine runs the fallback step's agent in place of terminal failure.

Both primary and fallback agents must be defined in the run's agents array.

Agent definitions for primary and fallback

[
 {
 "id": "00000000-0000-4000-8000-000000000020",
 "name": "primary_analyst",
 "role": "Senior analyst",
 "instructions": "Answer with full tool access.",
 "provider": {
 "provider_id": "openai",
 "model": "gpt-4o",
 "api_key_env": "OPENAI_API_KEY"
 }
 },
 {
 "id": "00000000-0000-4000-8000-000000000022",
 "name": "fallback_analyst",
 "role": "Backup analyst",
 "instructions": "Answer concisely without tools.",
 "provider": {
 "provider_id": "openai",
 "model": "gpt-4o-mini",
 "api_key_env": "OPENAI_API_KEY"
 }
 }
]

See Defining agents and Provider configuration.

Trace sequence

When fallback activates:

[
 { "kind": "StepStarted", "run_id": "r1", "step_id": "00000000-0000-4000-8000-000000000010", "agent_name": "primary_analyst" },
 { "kind": "StepFailed", "run_id": "r1", "step_id": "00000000-0000-4000-8000-000000000010", "error_code": "ProviderError" },
 { "kind": "StepFallbackActivated", "run_id": "r1", "step_id": "00000000-0000-4000-8000-000000000010", "primary_agent_name": "primary_analyst", "fallback_agent_name": "fallback_analyst" },
 { "kind": "StepStarted", "run_id": "r1", "step_id": "00000000-0000-4000-8000-000000000012", "agent_name": "fallback_analyst" },
 { "kind": "StepCompleted", "run_id": "r1", "step_id": "00000000-0000-4000-8000-000000000012", "duration_ms": 650 }
]

If the fallback step also fails and has no further fallback, the workflow terminal state is Failed with the last error_code (for example StepExecutionFailed or ProviderError per Error codes).

Combining with retry

Workflow or step retry may run before fallback triggers. Typical flow: transient error → RetryAttempted → success, or RetryExhausted → fallback if configured.

{
 "exec_config": {
 "retry": {
 "max_attempts": 2,
 "backoff": {
 "kind": "exponential",
 "base_ms": 1000,
 "multiplier": 2.0,
 "max_ms": 10000,
 "jitter_ms": 50
 }
 }
 }
}

Step-level retry_policy on the primary step overrides or merges per engine rules; validate behavior in Validation and testing with exec_config.test.

Test mode for fallback paths

Drive primary failure without live LLM:

{
 "recovery_enabled": false,
 "test": {
 "steps": {
 "00000000-0000-4000-8000-000000000010": {
 "fail_times": 1,
 "output": "primary fail",
 "then_output": "should not reach"
 },
 "00000000-0000-4000-8000-000000000012": {
 "output": "fallback success"
 }
 }
 }
}

Expect StepFallbackActivated then completion with fallback output.

Graph workflows

Fallback steps work on graph-backed steps referenced by nodes. Failure at a node step may activate that step's fallback_step_id before the scheduler evaluates outgoing edges. Test graph + fallback combinations in CI; edge routing after fallback depends on which step id completed.

Examples

Resilience samples under examples/ demonstrate fallback patterns alongside retry. Compare with Recovery and resume for run-level persistence, not step-level alternate agents.

Related pages

• Linear workflows
• Graph workflows
• Retry and backoff
• Execution model