# How the `ordered_backends()` Method Prioritizes User-Specified Backend Configurations in Agent-Reach

> Learn how ordered_backends() prioritizes your backend configurations in Agent-Reach. Discover how user preferences enhance the fallback chain without breaking it.

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

---

**The `ordered_backends()` method moves a user-specified backend to the front of the default list only if it exists in the channel's declared backends, ensuring user preferences take precedence while preventing invalid overrides from breaking the fallback chain.**

The `ordered_backends()` method in Agent-Reach determines which backend a channel attempts first when executing operations. Defined in the base channel class at [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), this method balances user customization with safe defaults by dynamically reordering backend priorities based on configuration settings while maintaining the original fallback sequence for unrecognized entries.

## How `ordered_backends()` Processes Backend Priorities

The method implements a deterministic selection algorithm that respects explicit user preferences without compromising the channel's ability to function when invalid configurations are provided.

### Starting with the Default Backend List

Each concrete channel class declares a class attribute `backends` containing an ordered list of candidate backends. For example, the Twitter channel defines `backends = ["twitter-cli", "OpenCLI", "bird CLI (legacy)"]` in [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py). The method creates a copy of this list to ensure modifications do not affect the original channel definition.

### Detecting User Configuration Overrides

The method accepts a `config` dictionary parameter and searches for an entry matching the pattern `"<channel_name>_backend"` using case-insensitive key matching. The value associated with this key represents the **user-preferred backend** that should take priority over the default ordering.

### Reordering Logic and Safety Guards

When a user-specified backend is detected, the method checks whether that backend exists in the channel's default list. If present, the method **moves that backend to index 0** (the front of the list), making it the first candidate attempted during channel operations. If the preferred backend is **not** present in the default list, the method returns the original ordering unchanged. This "stale-override" safety guard ensures that typographical errors or obsolete backend names in user configuration cannot accidentally disable all available backends.

## Implementation Example

Consider a scenario where a user prefers the `OpenCLI` backend for Twitter operations:

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

config = {"twitter_backend": "OpenCLI"}
channel = TwitterChannel()

# Returns ['OpenCLI', 'twitter-cli', 'bird CLI (legacy)']

preferred = channel.ordered_backends(config)
print(preferred)

```

The method detects `"twitter_backend"` in the configuration, verifies that `"OpenCLI"` exists in the default backends list, and reorders the list to prioritize the user's choice.

When an invalid backend is specified, the method preserves the original order:

```python
config = {"twitter_backend": "nonexistent-tool"}

channel = TwitterChannel()
print(channel.ordered_backends(config))

# Output: ['twitter-cli', 'OpenCLI', 'bird CLI (legacy)']

```

## Source Code Verification

The prioritization behavior is validated by the test suite in [`tests/test_channel_contracts.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_channel_contracts.py). The test `test_ordered_backends_override_moves_backend_to_front` confirms that valid overrides are placed at the front of the list, while `test_ordered_backends()` ensures the returned list remains a permutation of the original backends without duplication or loss of entries.

The configuration dictionary is typically constructed from CLI arguments or environment variables in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) before being passed to channel instances.

## Summary

- **`ordered_backends()`** produces an ordered list of candidate backends where the first element is the preferred backend to attempt.
- The method searches for user preferences using the `"<channel_name>_backend"` configuration key pattern.
- Valid user specifications are **moved to the front** of the backend list, while invalid specifications are ignored to preserve the fallback chain.
- The implementation is located in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) and is inherited by concrete channels like the Twitter implementation in [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py).

## Frequently Asked Questions

### What happens if I specify a backend that is not installed or configured?

The `ordered_backends()` method only verifies that the backend name exists in the channel's declared `backends` list. It does not check installation status or configuration validity. If the backend is present in the list but fails during execution, the channel's `probe()` or `read()` logic will attempt the next backend in the ordered sequence.

### Can I use environment variables to set the preferred backend?

Yes. The configuration dictionary passed to `ordered_backends()` is typically populated from environment variables and CLI arguments in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). Set a variable matching the pattern `<CHANNEL_NAME>_BACKEND` (case-insensitive) to inject your preference into the configuration object.

### Why does the method return the original order when the backend is not found?

This design prevents a "stale-override" scenario where a renamed or removed backend in user configuration could accidentally force the channel to skip all valid backends. By falling back to the default order, the channel maintains operational capability even when configuration files contain outdated entries.

### How does this method interact with the channel's `probe()` functionality?

The `ordered_backends()` method supplies the sequence used by `probe()` to test backend availability. The channel iterates through the returned list in order, attempting to initialize each backend until one succeeds. Prioritizing the user-specified backend ensures that user preferences are evaluated before the channel's built-in fallback options.