# How to Configure Multiple Backends for a Single Channel with Priority Ordering in Agent Reach

> Learn how to configure multiple backends for a single channel with priority ordering in Agent Reach using the ordered_backends() method. Optimize your backend probing now.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-14

---

**Agent Reach channels probe candidate backends in priority order, promoting a user-specified backend to the front via the `ordered_backends()` method in the base `Channel` class.**

Agent Reach treats each platform as a **channel** (e.g., Twitter, YouTube, Reddit) that can expose multiple candidate backends or tools. When the CLI needs to interact with a platform, the channel automatically probes its backends in a defined priority sequence until it finds a fully usable option. This configuration system resides in the `Panniantong/Agent-Reach` repository and requires no source code modifications to customize.

## Understanding the Backend Priority System

### The Channel Base Class

In [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) (lines 45-59), the `Channel` class defines the core infrastructure for managing multiple backends. Each concrete channel maintains a `backends` attribute—an ordered list of backend identifier strings—that establishes the default priority order. The first entry serves as the preferred default.

### How Ordering Works

The priority mechanism relies on two factors:

1. **Declaration order** in the channel class (e.g., `backends = ["twitter-cli", "OpenCLI", "bird CLI (legacy)"]` in [`twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/twitter.py) lines 11-17)
2. **User overrides** via the `ordered_backends(config)` method, which reads configuration keys and environment variables

## Configuration Methods

Agent Reach supports three ways to override backend priority. The configuration system is managed by [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), which handles persistent YAML storage and environment variable fallback (lines 30-34, 70-78).

### YAML Configuration File

The configuration file lives at `~/.agent-reach/config.yaml`. To prioritize a specific backend, add a key using the format `<channel>_backend`:

```yaml

# ~/.agent-reach/config.yaml

twitter_backend: OpenCLI

```

This promotes `OpenCLI` to the front of the list, even if `twitter-cli` is installed and listed first in the default `backends` array.

### Environment Variables

For temporary session overrides, use the environment variable format `<CHANNEL>_BACKEND` (uppercase):

```bash
export TWITTER_BACKEND=bird
python -m agent_reach.cli doctor

```

Environment variables take precedence over YAML entries because `Config.get()` checks the environment first.

### Programmatic Configuration

Use the `Config` class to set overrides programmatically:

```python
from agent_reach.config import Config

cfg = Config()
cfg.set("twitter_backend", "OpenCLI")

```

This persists the override to the YAML file and makes it available for subsequent channel operations.

## Implementation Details

### The ordered_backends() Method

As implemented in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) (lines 45-59), `ordered_backends(config)` performs the following logic:
- Reads the list from `self.backends`
- Checks for a user override via `config.get(f"{channel}_backend")` or the equivalent environment variable
- If found and valid, moves that backend to index 0 while preserving the relative order of remaining entries
- Ignores unknown values to prevent stale overrides from hiding working backends

### The check() Method

Concrete channels like `TwitterChannel` in [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) (lines 29-48) implement `check()` to iterate over `ordered_backends()` and select the first usable backend. The method:
- Iterates through the ordered list from `ordered_backends()`
- Selects the first backend reporting an "ok" status
- Falls back to the first "warn" status if none report "ok"
- Stores the chosen identifier in `self.active_backend`

## Practical Code Examples

### Inspecting Effective Ordering

To verify which backend will be selected before running operations:

```python
from agent_reach.channels.twitter import TwitterChannel
from agent_reach.config import Config

cfg = Config()
ch = TwitterChannel()
effective = ch.ordered_backends(cfg)
print(effective)  # Output: ['OpenCLI', 'twitter-cli', 'bird CLI (legacy)']

```

### Complete Configuration Workflow

```python
from agent_reach.config import Config
from agent_reach.channels.twitter import TwitterChannel

# Configure preference programmatically

cfg = Config()
cfg.set("twitter_backend", "OpenCLI")

# Initialize channel and detect active backend

ch = TwitterChannel()
status, msg = ch.check(cfg)
print(f"Status: {status}, Active Backend: {ch.active_backend}")

# Expected output: Status: ok, Active Backend: OpenCLI

```

## Summary

- **Backend lists** are defined in channel classes (e.g., `TwitterChannel.backends`) as ordered lists of strings
- **Priority overrides** use the config key `<channel>_backend` or environment variable `<CHANNEL>_BACKEND`
- **The `ordered_backends()` method** in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) (lines 45-59) promotes user preferences while preserving fallback order
- **Environment variables** take precedence over YAML configuration files due to `Config.get()` implementation
- **The `check()` method** selects the first "ok" backend from the ordered list and stores it in `active_backend`
- **Stale overrides** are ignored automatically, ensuring unknown backend names never hide working alternatives

## Frequently Asked Questions

### How does Agent Reach handle invalid backend overrides?

If you specify a backend that does not exist in the channel's `backends` list, `ordered_backends()` ignores the unknown value and preserves the original order. This safety mechanism, implemented in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) (lines 45-59), prevents stale configuration from hiding working backends.

### Can I use multiple configuration methods simultaneously?

Yes. Agent Reach reads configuration in a specific priority: environment variables override YAML file settings, which override default class declarations. The `Config.get()` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 70-78) implements this fallback chain.

### Where is the active backend stored after detection?

After the `check()` method runs, the selected backend identifier is stored in the channel instance's `self.active_backend` attribute. This is used by the diagnostic output in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) to report which tool is currently active for each channel.

### Do I need to restart the CLI after changing the config file?

No restart is necessary for YAML file changes, as `Config()` loads the file fresh upon instantiation. However, environment variable changes require restarting the process or shell session to take effect, as they are read once at startup.