How the ordered_backends Method Handles User Overrides in Agent Reach

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, 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 at lines 45-59. Its signature accepts an optional config parameter and returns a List[str] representing the candidate backends in probe order.

# 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 (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 loads settings from environment variables and configuration files, providing the get method that ordered_backends expects.

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.

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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}