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

# Fallback Adapter

> Automatic failover between multiple STT, LLM, or TTS providers

The Fallback Adapter provides automatic failover between multiple STT, LLM, or TTS providers. It switches providers on two conditions: first, on **errors** when a provider fails or becomes unavailable, and second, on **latency** when a provider stays slower than its configured budget. In both cases the system automatically switches to the next configured provider without interrupting the session.

## Features

<CardGroup cols={2}>
  <Card title="Automatic Fallback" icon="triangle-exclamation">
    Switches to lower-priority providers if the primary provider fails.
  </Card>

  <Card title="Latency-based Fallback" icon="gauge-high">
    Optionally switches providers when a component stays above its latency budget for several consecutive turns.
  </Card>

  <Card title="Cooldown-based Retry" icon="clock-rotate-left">
    Implements a cooldown period before retrying a failed provider, preventing immediate repeated failures.
  </Card>

  <Card title="Auto-Recovery" icon="rotate">
    Automatically switches back to a higher-priority provider once it becomes healthy again.
  </Card>

  <Card title="Permanent Disable" icon="ban">
    Permanently disables a provider after a configured number of failed recovery attempts.
  </Card>
</CardGroup>

## Error-based Fallback

Here is how you can implement error-based fallback providers for STT, LLM, and TTS in your agent's `Pipeline`. When a provider fails or becomes unavailable, the system switches to the next configured provider.

```python theme={null}
from zrt import Pipeline, FallbackSTT, FallbackLLM, FallbackTTS
from zrt.plugins import SarvamAISTT, DeepgramSTT, OpenAILLM, GoogleLLM, CartesiaTTS, DeepgramTTS

pipeline = Pipeline(
    stt=FallbackSTT(
        [SarvamAISTT(model="123"), DeepgramSTT(model="nova-2")],
        temporary_disable_sec=30.0,
        permanent_disable_after_attempts=3,
    ),
    llm=FallbackLLM(
        [OpenAILLM(model="gpt-5.4-nano-2026-03-17"), GoogleLLM(model="gemini-2.5-flash")],
        temporary_disable_sec=30.0,
        permanent_disable_after_attempts=3,
    ),
    tts=FallbackTTS(
        [CartesiaTTS(model="sonic-3.5"), DeepgramTTS(model="aura-2-thalia-en")],
        temporary_disable_sec=30.0,
        permanent_disable_after_attempts=3,
    ),
)
```

<Tip>Wrap any component's provider list in `FallbackSTT`, `FallbackLLM`, or `FallbackTTS` and pass it directly to `Pipeline`. The rest of your agent setup (`Agent`, `Room`, `on_enter`/`on_exit`, etc.) stays unchanged.</Tip>

### Configuration Options

You can configure the error-based fallback behavior using the following parameters:

<ParamField path="temporary_disable_sec" type="float">
  The duration (in seconds) to wait before retrying a failed provider.
</ParamField>

<ParamField path="permanent_disable_after_attempts" type="int">
  The maximum number of recovery attempts allowed before a provider is permanently disabled.
</ParamField>

## Latency-based Fallback

Beyond hard failures, the Fallback Adapter can switch providers when a healthy provider becomes too slow. This is useful for keeping conversations responsive when a provider degrades without erroring out.

<Note>
  Latency-based fallback is **off by default**. Set `latency_threshold_ms` on a component to enable it.
</Note>

* Each component measures a relevant latency metric: STT uses `stt_latency`, LLM uses `llm_ttft` (time to first token), and TTS uses `ttfb` (time to first byte).
* A provider is only switched after it stays above the threshold for `consecutive_latency_hits` turns in a row, avoiding switches caused by a single slow turn.
* Recovery and cooldown for a latency-disabled provider use the same `temporary_disable_sec` and `permanent_disable_after_attempts` settings as the error path.

To enable latency-based fallback, add `latency_threshold_ms` (and optionally `consecutive_latency_hits`) on top of the error-based configuration in your `Pipeline`:

```python theme={null}
pipeline = Pipeline(
    stt=FallbackSTT(
        [SarvamAISTT(model="123"), DeepgramSTT(model="nova-2")],
        temporary_disable_sec=30.0,
        permanent_disable_after_attempts=3,
        latency_threshold_ms=350,       # enable latency-based fallback
        consecutive_latency_hits=3,
    ),
    llm=FallbackLLM(
        [OpenAILLM(model="gpt-5.4-nano-2026-03-17"), GoogleLLM(model="gemini-2.5-flash")],
        temporary_disable_sec=30.0,
        permanent_disable_after_attempts=3,
        latency_threshold_ms=800,
        consecutive_latency_hits=3,
    ),
    tts=FallbackTTS(
        [CartesiaTTS(model="sonic-3.5"), DeepgramTTS(model="aura-2-thalia-en")],
        temporary_disable_sec=30.0,
        permanent_disable_after_attempts=3,
        latency_threshold_ms=250,
        consecutive_latency_hits=3,
    ),
)
```

### Configuration Options

You can configure the latency-based fallback behavior using the following parameters:

<ParamField path="latency_threshold_ms" type="int">
  Per-component latency budget in milliseconds (STT `stt_latency`, LLM `llm_ttft`, TTS `ttfb`). Off by default. Pass a value to enable latency-based fallback.
</ParamField>

<ParamField path="consecutive_latency_hits" type="int" default="3">
  The number of consecutive turns that must exceed `latency_threshold_ms` before switching providers.
</ParamField>

## References

<Tabs>
  <Tab title="Python">
    #### Examples

    <CardGroup cols={2}>
      <Card title="Fallback Adapter" icon="github" href="https://github.com/ZeroRuntimeAI/zrt-python-sdk-examples/blob/main/features/fallback.py">
        Checkout the full implementation on GitHub
      </Card>
    </CardGroup>

    #### SDK Reference

    <CardGroup cols={2}>
      <Card title="Pipeline" icon="book" href="/api-reference/python/core/pipeline">
        `Pipeline` in the Python API reference.
      </Card>

      <Card title="FallbackSTT" icon="book" href="/api-reference/python/core/pipeline#fallbackstt">
        `FallbackSTT` in the Python API reference.
      </Card>

      <Card title="FallbackTTS" icon="book" href="/api-reference/python/core/pipeline#fallbacktts">
        `FallbackTTS` in the Python API reference.
      </Card>

      <Card title="FallbackLLM" icon="book" href="/api-reference/python/core/pipeline#fallbackllm">
        `FallbackLLM` in the Python API reference.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>