How Agent Reach Handles Multi-Backend Routing with Preferred and Fallback Options

Agent Reach implements multi-backend routing by maintaining an ordered list of candidate backends per channel, allowing user overrides to reorder the priority list, and probing each candidate in sequence until finding one that reports ok or warn status, storing the final selection in active_backend.

Agent Reach abstracts every social platform as a channel capable of being serviced by multiple command-line tools. The routing logic resides in the abstract base class Channel within agent_reach/channels/base.py, ensuring consistent multi-backend failover across all platform implementations from Twitter to Reddit.

Backend Declaration and Preference Order

Each concrete channel defines a backends class attribute as an ordered list where the first element represents the preferred backend and subsequent entries serve as fallbacks. This declaration determines the default probing sequence when no user override is present.

For example, in agent_reach/channels/twitter.py, the TwitterChannel class declares:

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

This configuration ensures that twitter-cli is attempted first, followed by OpenCLI if the primary fails, and finally the legacy option.

User Override Mechanism

Users can force a specific backend via configuration keys or environment variables, bypassing the default preference order. The system recognizes patterns matching <channel>_backend for configuration files or *_BACKEND for environment variables.

The method Channel.ordered_backends() in agent_reach/channels/base.py constructs the candidate list by moving the overridden backend to the front while preserving the relative order of remaining options. This ensures that user preferences take precedence without completely discarding fallback options.

The Probing Sequence and Status Semantics

In each channel's check() method, the code loops over ordered_backends(config) and executes lightweight health probes—typically via probe_command or custom routines. Each probe returns a tuple (status, message) according to specific semantics:

• ok — The backend is fully usable (installed, executable, and authenticated)
• warn — The backend exists but requires extra configuration (e.g., missing auth token)
• off — The backend is not installed
• error — The backend is installed but broken (e.g., stale shim or missing JavaScript runtime)

The probing loop selects the first backend reporting status == "ok". If no backends report ok, the first status == "warn" is selected. The winning backend is stored in self.active_backend, making the routing transparent to downstream code.

Fallback Guarantees

Because the probe continues after encountering a warn result, a later backend that reports ok can still be chosen over an earlier one that merely warned. This prevents partially-configured backends—such as an unauthenticated twitter-cli—from blocking healthier fallbacks like OpenCLI.

Cross-Channel Consistency

All channels inherit the same routing contract from the abstract Channel class. The test suite in tests/test_channels.py enforces this consistency by asserting that ordered_backends() returns a valid permutation of the declared backends list, that configuration overrides are honored, and that active_backend is always either None or a string after check() completes.

OpenCLI Backend Implementation

The OpenCLI backend, frequently used as a fallback across multiple channels, implements sophisticated probing logic in agent_reach/backends/opencli.py. It performs a two-stage validation: first checking the CLI version, then executing opencli daemon status to verify the daemon and Chrome extension state.

Even if the Chrome extension reports as "sleeping," the opencli_status().ready property may still indicate the backend is usable, allowing it to serve as a functional fallback when primary backends fail or require authentication.

Practical Code Examples

Force a specific backend using configuration:

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

# User wants to force the legacy bird CLI

cfg = Config()
cfg["twitter_backend"] = "bird CLI (legacy)"

channel = TwitterChannel()
status, msg = channel.check(cfg)          # ← probes in order: bird → twitter-cli → OpenCLI

print(status, msg)                        # → e.g. "ok", "bird CLI 可用…"

print(channel.active_backend)             # → "bird CLI (legacy)"

Generic usage without override:

from agent_reach.channels.reddit import RedditChannel

ch = RedditChannel()
status, msg = ch.check()                  # no override → Ordered: ["OpenCLI", "rdt-cli"]

print(f"Reddit will use {ch.active_backend}")   # → "OpenCLI" if available, else "rdt-cli"

Inspect candidate order without probing:

from agent_reach.channels.youtube import YouTubeChannel
ch = YouTubeChannel()
print(ch.ordered_backends())              # → ["yt-dlp"] (single‑backend channel)

Summary

• Channel abstraction: Every platform inherits from Channel in agent_reach/channels/base.py, which defines the multi-backend routing contract.
• Ordered fallback: The backends list declares preference order, with ordered_backends() handling user overrides via config keys or environment variables.
• Health probing: The check() method probes candidates in priority order, selecting the first ok or falling back to the first warn if none are fully healthy.
• Active selection: The chosen backend is stored in active_backend, providing transparent access to the selected tool.
• Cross-platform consistency: All channels follow the same routing logic, verified by tests/test_channels.py.

Frequently Asked Questions

How does Agent Reach determine which backend to use for a specific channel?

Agent Reach checks the channel's ordered_backends() method, which returns a prioritized list starting with any user-specified override followed by the default backends list. It then probes each candidate in sequence, selecting the first that reports ok status, or warn if no ok statuses are found.

Can I force a specific backend instead of relying on automatic selection?

Yes. Set the configuration key <channel>_backend (e.g., twitter_backend) or the corresponding *_BACKEND environment variable. The ordered_backends() method will move your specified backend to the front of the candidate list while maintaining the original order for remaining options.

What happens if the preferred backend is only partially configured?

If a backend returns warn status (indicating it exists but lacks proper configuration), the probing loop continues to evaluate subsequent fallbacks. If a later backend returns ok, it will be selected instead. This ensures that a partially-configured primary cannot block a fully-functional fallback.

Where is the multi-backend routing logic implemented?

The core routing logic resides in the abstract Channel class within agent_reach/channels/base.py. This file defines the backends attribute, the ordered_backends() method for handling overrides, and the default check() implementation that performs the probing sequence. Concrete channels like TwitterChannel and RedditChannel inherit this behavior and customize their specific backends lists.

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