# How to Customize Backend Priority for a Specific Platform in Agent Reach

> Customize Agent Reach backend priority for specific platforms. Set platform_backend keys in config or environment variables to reorder backends efficiently.

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

---

**You can customize backend priority in Agent Reach by setting a `<platform>_backend` key in your configuration file or the corresponding `<PLATFORM>_BACKEND` environment variable, which the `Channel.ordered_backends()` method uses to reorder the candidate list while preserving fallbacks.**

Agent Reach is an open-source automation framework that manages multiple upstream tools (backends) for each social platform. When you need to customize backend priority for a specific platform, the system provides a configuration-driven override mechanism that doesn't require code modifications. This logic is implemented in the `Channel` base class located in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py).

## How Backend Priority Works

Every platform channel in Agent Reach defines an ordered list of supported backends. The first entry represents the preferred tool, while subsequent entries serve as automatic fallbacks if the primary tool is unavailable.

### Default Backend Ordering

Each channel class defines a `backends` attribute containing an ordered list of strings. For example, a Twitter channel might define:

```python
backends = ["twitter-cli", "bird CLI (legacy)", "OpenCLI"]

```

The framework probes these backends in sequence during health checks, selecting the first one reporting status `"ok"` as the active backend.

### The `ordered_backends()` Method

The `Channel` base class provides 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) to handle user overrides while maintaining the fallback chain:

```python
def ordered_backends(self, config=None) -> List[str]:
    """Candidate backends in probe order, honoring the user override."""
    candidates = list(self.backends)
    override = config.get(f"{self.name}_backend") if config else None
    if override:
        for i, b in enumerate(candidates):
            if b == override or b.startswith(override):
                candidates.insert(0, candidates.pop(i))
                break
    return candidates

```

This method checks for a configuration key matching `<channel_name>_backend`. When found, it moves the matching backend to the front of the list without removing the other candidates. Unknown values are ignored, ensuring that a stale override never hides a working backend.

## Configuration Methods

Agent Reach supports two configuration sources that follow a specific precedence order: YAML configuration files and environment variables.

### YAML Configuration File

Create or edit `~/.agent-reach/config.yaml` to specify backend preferences persistently:

```yaml

# ~/.agent-reach/config.yaml

twitter_backend: "bird"
youtube_backend: "deno"
xiao_hong_shu_backend: "official-api"

```

The key format follows `<platform>_backend` using lowercase platform names and underscores.

### Environment Variables

For temporary overrides or containerized deployments, use uppercase environment variables with the pattern `<PLATFORM>_BACKEND`:

```bash
export TWITTER_BACKEND=bird
export YOUTUBE_BACKEND=deno
export XIAO_HONG_SHU_BACKEND=official-api

```

### Configuration Precedence

The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 75-84) implements the merging logic through the `get()` method:

```python
def get(self, key: str, default: Any = None) -> Any:
    if key in self.data:
        return self.data[key]       # file wins

    env_val = os.environ.get(key.upper())
    if env_val:
        return env_val              # then env var

    return default

```

Configuration file values take precedence over environment variables, ensuring that explicit file settings override shell-level defaults.

## Practical Implementation

When a channel executes its health check, it calls `ordered_backends()` to determine the probe sequence. For example, in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 70-77), the `check()` method iterates through the reordered list:

```python
for backend in self.ordered_backends(config):
    # probe each backend in the reordered list

    status = self._probe_backend(backend)
    if status == "ok":
        self.active_backend = backend
        break

```

This ensures that your custom priority is respected during the backend selection process.

## Code Examples

### Setting Backend Priority via Config File

Create a platform-specific backend override in your Agent Reach configuration:

```yaml

# ~/.agent-reach/config.yaml

twitter_backend: "bird CLI (legacy)"
youtube_backend: "deno"

```

### Setting Backend Priority via Environment Variable

Apply an immediate override without modifying files:

```bash
export TWITTER_BACKEND="bird"
agent-reach check twitter

```

### Programmatic Usage

When using Agent Reach as a library, pass a `Config` object to respect the backend priority:

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

cfg = Config()                     # loads file + env vars

tw = TwitterChannel()
status, msg = tw.check(cfg)       # respects the backend override

print(status, tw.active_backend)  # e.g. "ok", "bird CLI (legacy)"

```

### Verifying the Override

The test suite in [`tests/test_channel_contracts.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_channel_contracts.py) (lines 86-94) demonstrates how to verify the reordering behavior:

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

ch = TwitterChannel()
ordered = ch.ordered_backends({"twitter_backend": "bird"})
assert ordered[0] == "bird CLI (legacy)"   # override moved to front

```

## Summary

- **Default behavior**: Each `Channel` subclass defines an ordered `backends` list where the first element is preferred and others serve as fallbacks.
- **Override mechanism**: Set `<platform>_backend` in `~/.agent-reach/config.yaml` or `<PLATFORM>_BACKEND` as an environment variable to move a specific backend to the front of the probe order.
- **Precedence rules**: Configuration file values override environment variables, which override default ordering.
- **Safety feature**: Unknown backend values in configuration are ignored, preventing total system failure from stale overrides.
- **Implementation location**: The core logic resides in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) (`ordered_backends()`) and [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (`get()`).

## Frequently Asked Questions

### What happens if I specify a backend that doesn't exist?

Agent Reach ignores unknown backend values in the configuration. The `ordered_backends()` method only reorderes the list if it finds a matching backend string or prefix. If no match exists, the default ordering remains unchanged, preventing configuration errors from breaking the channel functionality.

### Can I set different backends for different platforms simultaneously?

Yes. Each platform uses an independent configuration key following the `<platform>_backend` pattern. You can set `twitter_backend: "bird"` and `youtube_backend: "deno"` in the same configuration file, and each channel will respect only its own override without affecting others.

### Does the environment variable override the config file?

No. According to the `Config.get()` implementation in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the configuration file takes precedence over environment variables. The method checks `self.data` (the YAML file contents) first, then falls back to environment variables only if the key is not present in the file.

### Which source files contain the backend priority logic?

The primary implementation is in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) (lines 45-59) containing the `ordered_backends()` method. Configuration loading logic is in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 75-84). Individual channels like [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 70-77) demonstrate how the reordered list is consumed during health checks.