# How Agent Reach Selects the Best Tool for a Platform: Backend Selection Explained

> Discover how Agent Reach selects the best tool for a platform. Learn about backend selection, health status checks, and prioritizing user configurations.

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

---

**Agent Reach selects the best tool for a platform by probing an ordered list of candidate backends, prioritizing user-configured overrides, and activating the first backend that returns an "ok" health status.**

Agent Reach is an open-source Python framework that abstracts social media interactions through a channel-based architecture. When your agents need to post to Twitter or scrape YouTube, the framework must determine which external CLI tool is installed, authenticated, and functional. Understanding how Agent Reach selects the best tool for a platform reveals a deterministic probing mechanism that balances user preferences with automatic fallbacks.

## Channel Architecture and Backend Declaration

Agent Reach treats each internet platform as a **channel**—a subclass of `agent_reach.channels.base.Channel` that declares an ordered list of possible backends in the class attribute `backends`. These backends represent external tools capable of interacting with the platform.

For example, the Twitter channel defines multiple CLI options in order of preference:

```python

# agent_reach/channels/twitter.py

class TwitterChannel(Channel):
    name = "twitter"
    description = "Twitter/X 推文"
    backends = ["twitter-cli", "OpenCLI", "bird CLI (legacy)"]
    # ...

```

Each channel implements its own health check logic, but inherits the core selection mechanism from the base class.

## Step 1: Ordering Backends with User Overrides

Before probing begins, `Channel.ordered_backends()` in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) prepares the candidate list. This method checks for user configuration overrides that can reorder the backend priority.

If a user specifies a preferred backend via the `{channel}_backend` configuration key (e.g., `twitter_backend`), that backend moves to the front of the list:

```python

# agent_reach/channels/base.py

def ordered_backends(self, config=None) -> List[str]:
    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 ensures user preferences take precedence over the default declaration order.

## Step 2: Runtime Health Probing

Each channel implements a `check()` method that iterates over the ordered backends and probes each candidate using `agent_reach.probe.probe_command`. This probe runs a lightweight command (e.g., `twitter status`) to verify the tool is not only installed but also functional and authenticated.

The probe returns a tuple `(status, message)` where status can be:
- `"ok"` – Tool is fully functional
- `"warn"` – Tool is installed but has issues (e.g., expired tokens)
- `"error"` – Tool is broken or misconfigured

```python

# Simplified probing logic from agent_reach/channels/twitter.py

for backend in self.ordered_backends(config):
    if backend == "twitter-cli":
        result = self._check_twitter_cli()
    elif backend == "OpenCLI":
        result = self._check_opencli()
    # ...

    
    if result is None:  # Not installed

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

```

## Step 3: Selecting the First Healthy Backend

Agent Reach employs a **"first-OK wins"** selection strategy. After collecting probe results, the channel selects the first backend with an `"ok"` status. If no backend reports `"ok"`, it falls back to the first `"warn"` result. Only when all candidates return `"error"` does the channel report a failure.

```python

# Selection logic from agent_reach/channels/twitter.py

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

```

The selected backend is stored in `self.active_backend`, making it available for subsequent operations and status reporting.

## Inspecting and Configuring Tool Selection

Users can override the automatic selection using the configuration system. To force a specific tool, set the appropriate backend key:

```bash

# Force OpenCLI for Twitter interactions

agent-reach configure twitter_backend OpenCLI

```

You can verify which tool Agent Reach selected by running the doctor command:

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

cfg = Config()
cfg.set("twitter_backend", "OpenCLI")  # Optional: force a specific backend

results = check_all(cfg)
print(format_report(results))

```

This outputs the active backend for each platform, showing which tool will actually execute operations:

```

twitter: ✅ OpenCLI 可用（复用浏览器登录态）   (status: ok)
youtube: ✅ yt-dlp 已安装                (status: ok)

```

## Summary

- **Channel-based architecture**: Each platform (Twitter, YouTube, Reddit) is a `Channel` subclass with a declared `backends` list in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py).
- **User overrides take precedence**: The `ordered_backends()` method checks for `{channel}_backend` config keys to reorder candidates before probing.
- **Functional probing**: [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) verifies tools are installed and authenticated, not merely present in PATH.
- **First-OK wins**: Agent Reach selects the first backend with `"ok"` status, falls back to `"warn"`, and only fails if all return `"error"`.
- **Active backend recording**: The selected tool is stored in `self.active_backend` and reported via `agent_reach.doctor`.

## Frequently Asked Questions

### How do I force Agent Reach to use a specific tool instead of auto-selecting?

Set the `{channel}_backend` configuration key to your preferred tool. For example, run `agent-reach configure twitter_backend OpenCLI` or use the Python API: `config.set("twitter_backend", "OpenCLI")`. This override moves your specified backend to the front of the candidate list before probing begins.

### What happens if no backend returns an "ok" status?

Agent Reach implements a graceful degradation strategy. If no backend reports `"ok"`, it selects the first backend with `"warn"` status. Only when every candidate returns `"error"` or is not installed does the channel raise an error, allowing operations to proceed with degraded functionality when possible.

### Where does Agent Reach store the selected backend?

The active backend is stored in the `active_backend` instance attribute of the channel class after selection. This value persists for the channel instance lifecycle and is displayed in `agent_reach.doctor` reports, which orchestrate checks across all channels and format the results for user visibility.

### Which source files control the tool selection logic?

The selection logic spans four key files: [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) defines the `ordered_backends()` method and `Channel` ABC; [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) (and similar platform files) implement platform-specific probing; [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) contains the low-level `probe_command` function; and [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) orchestrates health checks across all channels.