# How the ordered_backends Method Handles User Overrides in Agent Reach

> Discover how Agent Reach's ordered_backends method prioritizes user-specified backends for probes, ensuring fallbacks remain while enhancing custom configurations.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-01

---

**The `ordered_backends` method in Agent Reach's base channel class promotes a user-specified backend to the front of the probe list by matching against a `{channel}_backend` configuration key, while preserving the original set of candidates as a fallback.**

Agent Reach is an open-source framework that abstracts platform interactions through configurable channels. The `ordered_backends` method, defined in the core channel base class at [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), enables users to override the default backend probing priority while maintaining a robust fallback chain.

## Implementation in the Base Channel Class

The `ordered_backends` method is implemented in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) at lines 45-59. Its signature accepts an optional `config` parameter and returns a `List[str]` representing the candidate backends in probe order.

```python

# agent_reach/channels/base.py (lines 45-59)

def ordered_backends(self, config=None) -> List[str]:
    """Candidate backends in probe order, honoring the user override."""
    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

```

The method begins with a copy of the channel's static `backends` list, which defines the author's intended priority order (for example, `["yt-dlp", "node", "deno"]` for YouTube). This list serves as the default ordering before any user preferences are applied.

## How User Overrides Modify the Probe Order

When a configuration object is provided, the method looks for a key named `{channel}_backend`, where `{channel}` is replaced by the specific channel's name. For instance, the **TwitterChannel** expects `twitter_backend`, while **YouTubeChannel** looks for `youtube_backend`.

The override value supports both exact matches and prefix matching. If the configured backend equals the override string or starts with it, the method removes that backend from its current position and inserts it at index 0. This allows short names like `"bird"` to match full backend names such as `"bird CLI (legacy)"` without requiring the exact string.

The promotion logic ensures that the user-preferred backend is probed first, while all other backends shift down in priority but remain available as fallbacks.

## Safety-First Fallback Behavior

If the override string does not match any known backend in the candidate list, the method returns the original list unchanged. This **graceful degradation** prevents stale or misspelled configuration values from hiding functional backends entirely.

The unit tests in [`tests/test_channel_contracts.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_channel_contracts.py) (lines 86-98) verify this behavior explicitly. When an unknown override like `"no-such-tool"` is provided, the returned list matches the original `backends` list exactly, ensuring the channel can still attempt to locate usable tools.

## Practical Code Examples

### Using a Config Object

The `Config` class from [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) loads settings from environment variables and configuration files, providing the `get` method that `ordered_backends` expects.

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

# Assumes the user set TWITTER_BACKEND=bird in environment

cfg = Config()
channel = TwitterChannel()
backend_order = channel.ordered_backends(cfg)

# Result: ["bird CLI (legacy)", ...]

print("Probe order:", backend_order)

```

### Direct Dictionary Override

For scripts or testing scenarios, you can pass a plain dictionary directly.

```python
from agent_reach.channels.youtube import YouTubeChannel

override = {"youtube_backend": "yt-dlp"}
yt = YouTubeChannel()
print(yt.ordered_backends(override))

# Output: ["yt-dlp", "node", "deno"]

```

### Handling Unknown Overrides

When the specified backend does not exist, the method preserves the original ordering.

```python
from agent_reach.channels.reddit import RedditChannel

unknown = {"reddit_backend": "nonexistent"}
rd = RedditChannel()
print(rd.ordered_backends(unknown))

# Output: Original backends list unchanged

```

## Summary

- **User preference promotion**: The `ordered_backends` method moves a user-specified backend to the front of the probe list by matching the `{channel}_backend` configuration key.
- **Prefix matching support**: Short override names can match longer backend names if they start with the override string.
- **Immutable candidate set**: The method returns a permutation of the original `backends` list; no candidates are removed, only reordered.
- **Graceful fallback**: Unknown or misspelled overrides result in the default ordering being returned unchanged, preventing tool discovery failures.

## Frequently Asked Questions

### What configuration key format does ordered_backends look for?

The method constructs the configuration key by appending `_backend` to the channel's name attribute. For a `TwitterChannel`, the key is `twitter_backend`; for `YouTubeChannel`, it is `youtube_backend`. This string is then used to retrieve the override value from the provided config object or dictionary.

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

If the override value does not match any candidate backend (either exactly or as a prefix), the method returns the original `backends` list unchanged. This safety mechanism ensures that a typo or outdated configuration does not prevent the channel from discovering usable backends.

### Does ordered_backends remove backends from the list or just reorder them?

The method only reorders the list. It removes the matched backend from its current index and inserts it at position 0, but the total set of backends remains identical to the original. This guarantees that all configured fallback options remain available if the preferred backend fails.

### Can I use partial names to match backends?

Yes. The matching logic at lines 53-56 in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) checks if the backend name equals the override OR starts with the override string. This allows you to use shorthand identifiers like `"bird"` to match full names like `"bird CLI (legacy)"` without specifying the complete string.