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

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.

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:

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 (lines 45-59) to handle user overrides while maintaining the fallback chain:

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:

# ~/.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:

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 (lines 75-84) implements the merging logic through the get() method:

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 (lines 70-77), the check() method iterates through the reordered list:

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:

# ~/.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:

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:

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 (lines 86-94) demonstrates how to verify the reordering behavior:

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 (ordered_backends()) and 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, 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 (lines 45-59) containing the ordered_backends() method. Configuration loading logic is in agent_reach/config.py (lines 75-84). Individual channels like agent_reach/channels/xiaohongshu.py (lines 70-77) demonstrate how the reordered list is consumed during health checks.

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