# How Agent‑Reach Implements Platform‑Specific Backend Selection for Channels

> Discover how Agent-Reach selects platform-specific backends for channels using a two-stage algorithm featuring user overrides and sequential probing for optimal health.

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

---

**Agent‑Reach uses a deterministic two‑stage algorithm: first it builds an ordered list of backend candidates (respecting user overrides), then it probes each candidate in sequence until it finds a healthy (`ok`) or partially healthy (`warn`) backend to activate.**

The **platform‑specific backend selection** logic in Agent‑Reach determines which external command‑line tool or built‑in implementation handles `read` and `search` operations for each supported internet service. This mechanism lives in the `Channel` base class and ensures reliable fallback behavior across Twitter, YouTube, Reddit, and other platforms.

## Stage 1: Building the Candidate List with ordered_backends()

Each channel declares a static `backends` list representing its preferred tools in priority order. Before any health checks run, the system calls `Channel.ordered_backends()` in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) to prepare the candidate list.

This method performs two critical operations:

1. **Copy the static list** – Creates a mutable copy of the channel’s default backends.
2. **Apply user overrides** – Checks for a configuration key `<channel>_backend` or environment variable `<CHANNEL>_BACKEND`. If found, the specified backend moves to the front of the list. Unknown overrides are silently ignored to prevent stale configurations from hiding working alternatives.

```python
def ordered_backends(self, config=None) -> List[str]:
    """
    Return the backend candidates, applying any user‑specified override.
    """
    candidates = list(self.backends)                     # copy static list

    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))  # move to front

                break
    return candidates

```

*Source: [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) (lines 45‑60)*

This design guarantees **deterministic fallback**—the same backend is chosen consistently across runs unless the user explicitly overrides it.

## Stage 2: Probing and Selecting the Active Backend

Once the ordered list is ready, the channel‑specific `check()` method probes each candidate. The reference implementation in [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) demonstrates the selection logic shared across all channels.

The probing process works as follows:

- **Iterate through candidates** – For each backend in the ordered list, invoke a lightweight health probe (via `probe_command` in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) or backend‑specific helpers like `opencli_status()` in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py)).
- **Evaluate status** – Each probe returns one of three states:
  - **`ok`** – The backend is installed and fully functional.
  - **`warn`** – The backend is present but misconfigured (e.g., missing credentials).
  - **`error`** or **`broken`** – The command exists but cannot execute or timed out.
- **Select winner** – The first backend reporting **`ok`** becomes `active_backend`. If none are `ok`, the first **`warn`** is selected. If only errors remain, the channel reports an overall failure.

```python
def check(self, config=None):
    """
    Probe each backend in order; the first 'ok' wins, otherwise the first 'warn'.
    """
    self.active_backend = None
    findings = []

    for backend in self.ordered_backends(config):
        if backend == "twitter-cli":
            result = self._check_twitter_cli()
        elif backend == "OpenCLI":
            result = self._check_opencli()
        elif backend == "bird CLI (legacy)":
            result = self._check_bird()
        else:
            continue

        if result is None:               # backend not installed

            continue
        findings.append((backend, *result))

    # Prefer ok → warn → error

    for wanted in ("ok", "warn"):
        for backend, status, message in findings:
            if status == wanted:
                self.active_backend = backend
                return status, message

    # Only errors left (or nothing found)

    if findings:
        return "error", "\n".join(m for _, _, m in findings)

    return "warn", "Twitter CLI 未安装。安装方式：..."

```

*Source: [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) (lines 19‑48)*

The resulting `active_backend` value persists in `Channel.active_backend`, which the CLI, doctor, and other subsystems query to determine which commands to invoke.

## Key Source Files in the Selection Pipeline

| File | Purpose |
|------|---------|
| [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) | Defines the abstract `Channel` class, `ordered_backends()` method, and default `check()` skeleton. |
| [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) | Concrete implementation showing backend probing and selection priority logic. |
| [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) | Provides `opencli_status()` helper used by multiple channels to validate OpenCLI availability. |
| [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) | Implements `probe_command()` with timeout and retry logic for low‑level health checks. |
| [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) | Aggregates channel checks via `check_all()` to report system‑wide backend status. |

## Practical Usage Example

When running diagnostics or executing platform operations, the system relies on the selected backend stored in `active_backend`:

```python
from agent_reach.doctor import check_all
from agent_reach.config import Config

cfg = Config()
status_report = check_all(cfg)          # runs each channel's check()

print(status_report["twitter"])         # e.g., ('ok', 'OpenCLI 可用…')

```

The doctor harness automatically triggers the two‑stage selection process for every configured channel, ensuring the most appropriate backend is active before any operations begin.

## Summary

- **Agent‑Reach** treats every platform as a **channel** with an ordered list of candidate backends.
- **Stage 1** (`ordered_backends`) applies user overrides via configuration or environment variables, then returns the prioritized list.
- **Stage 2** (`check`) probes each candidate in order, selecting the first `ok` backend, falling back to `warn`, or reporting an error if none are viable.
- The active backend is stored in `Channel.active_backend` and used by the CLI and diagnostic tools to execute platform operations.
- This architecture ensures **graceful degradation** (automatic fallback to secondary tools) and **user‑controlled priority** (explicit backend selection via config).

## Frequently Asked Questions

### How do I force Agent‑Reach to use a specific backend for a channel?

Set the configuration key `<channel>_backend` in your config file or export the environment variable `<CHANNEL>_BACKEND`. For example, `TWITTER_BACKEND=OpenCLI` moves OpenCLI to the front of the candidate list for the Twitter channel. Invalid values are ignored, so the system falls back to the default ordering if your specified backend is unavailable.

### What happens if all backends report errors during the check phase?

If every candidate returns an `error` or `broken` status, the channel’s `check()` method returns an error status and diagnostic message. The doctor tool aggregates this into the system health report, and the channel will not perform read or search operations until at least one backend becomes healthy or you install a missing dependency.

### Where does the actual health probing occur?

The low‑level execution happens in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) via `probe_command()`, which runs commands with configurable timeouts and retries. Backend‑specific checks (like OpenCLI status) delegate to helpers in [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py), while channel‑specific implementations (like `TwitterChannel.check`) coordinate the overall probing workflow.

### Can I see which backend is currently active for a channel without running a full check?

Yes—the `active_backend` attribute on any Channel instance stores the selection result after `check()` runs. The doctor command ([`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)) displays this information for all channels, showing both the selected backend and its health status (ok/warn/error) alongside diagnostic messages.