# How Agent Reach Handles Bilibili Access: Channel Architecture and Backend Selection

> Discover how Agent Reach manages Bilibili access with its flexible channel architecture, intelligently selecting between bili-cli, OpenCLI, or a public API for optimal performance.

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

---

**Agent Reach abstracts Bilibili access through a configurable channel architecture that automatically probes and selects between the `bili-cli` tool, OpenCLI integration, or a zero-dependency public API based on availability and health status.**

Agent Reach treats Bilibili as a modular *channel*, routing requests through a pluggable backend system implemented in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py). This design, extending the generic contract defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), allows the framework to adapt to diverse runtime environments—whether a user has local CLI tools installed or requires a dependency-free fallback—while presenting a unified interface for video metadata retrieval, subtitle extraction, and search operations.

## Backend Selection and Priority Order

The Bilibili channel declares its candidate backends through the class attribute `backends`, specifying the probe order:

```python
backends = ["bili-cli", "OpenCLI", "B站搜索 API"]

```

As implemented in [[`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) lines 36‑40](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py#L36-L40), this list determines the default priority. The `Channel.ordered_backends()` method—defined in [[`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) lines 45‑59](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py#L45-L59)—respects the user override environment variable `BILIBILI_BACKEND`, allowing you to force a specific implementation regardless of the default order.

## Health Probing Mechanism

When `agent_reach doctor` runs, `BilibiliChannel.check()` iterates over the ordered backends and executes lightweight health probes to determine the first viable option. The method collates results, records fallback notes, and returns a `(status, message)` tuple. If no backend responds, it returns an "off" status with remediation advice (see [[`bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/bilibili.py) lines 46‑80](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py#L46-L80)).

### bili-cli Probe

The channel first attempts to locate the `bili-cli` tool by executing `bili --version` via `probe_command()` ([[`bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/bilibili.py) lines 82‑94](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py#L82-L94)). The probe distinguishes three states:

- **Missing** – The command is not found; the backend is skipped.
- **Broken** – The command exists but reports a non-zero status; a warning is issued with a reinstall hint.
- **Healthy** – The version check passes, setting `self.active_backend = "bili-cli"` and returning an "ok" status.

### OpenCLI Integration

Next, the channel probes the `OpenCLI` backend by calling `opencli_status()` ([[`bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/bilibili.py) lines 96‑110](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py#L96-L110)). This backend is preferred for subtitle retrieval when available, as indicated by the status object returned from the OpenCLI integration layer.

### B站搜索 API Fallback

Finally, the channel tests the zero-dependency public API by performing an HTTP GET against `https://api.bilibili.com/x/web-interface/search/all/v2?keyword=test&page=1`. The helper `_search_api_ok()` ([[`bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/bilibili.py) lines 24‑33](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py#L24-L33)) returns `True` only when the response contains `code == 0`. This backend provides search capability without requiring external CLI installation.

## Runtime Usage and Configuration

Once `check()` succeeds, the active backend identifier is stored in `self.active_backend`. Subsequent `read()` or `search()` calls dispatch to the appropriate implementation, allowing agents to fetch video details or subtitles without knowing the underlying provider.

Run the diagnostic command to verify your current setup:

```bash
python -m agent_reach.cli doctor

```

The output includes the active Bilibili backend and its capabilities, such as:

```

Bilibili: bili-cli 可用（搜索/热门/排行/视频详情/音频，无需登录；字幕需 OpenCLI。上游 2026-03 起停更）

```

To force a specific backend (for example, to always use the public API), set the environment variable before running:

```bash
export BILIBILI_BACKEND="B站搜索 API"
python -m agent_reach.cli doctor

```

In Python, the core router automatically selects the active Bilibili backend when you specify the platform:

```python
from agent_reach.core import AgentReach

ar = AgentReach()
results = ar.search("python tutorial", platform="bilibili")
print(results)  # Output varies by backend: structured CLI output or raw JSON from the API

```

## Summary

- **Channel Architecture** – Bilibili access is encapsulated in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py), extending the base contract from [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py).
- **Three-Tier Backend System** – The channel probes `bili-cli`, `OpenCLI`, and `B站搜索 API` in order, selecting the first healthy option.
- **Automatic Failover** – If `bili-cli` is missing or broken, the system transparently falls back to OpenCLI or the public search API.
- **User Override** – Set `BILIBILI_BACKEND` to bypass automatic selection and force a specific implementation.
- **Zero-Dependency Option** – The `B站搜索 API` backend requires no local installation, enabling search functionality in restricted environments.

## Frequently Asked Questions

### How does Agent Reach choose which Bilibili backend to use?

Agent Reach calls `ordered_backends()` to retrieve the priority list, respecting the `BILIBILI_BACKEND` environment variable if set. It then iterates through `bili-cli`, `OpenCLI`, and `B站搜索 API`, executing health checks via `check()` until it finds a responsive backend. The first healthy backend becomes the active channel for subsequent operations.

### What happens if no Bilibili backend is available?

If all probes fail—meaning `bili-cli` is not installed, OpenCLI is unreachable, and the public API returns a non-zero code—the `check()` method returns an "off" status with a tuple containing a remediation message. The `agent_reach doctor` command surface this status, advising users to install the missing CLI tools or check network connectivity.

### Can I force Agent Reach to use a specific Bilibili backend?

Yes. Export the `BILIBILI_BACKEND` environment variable with the exact string from the `backends` list (e.g., `export BILIBILI_BACKEND="bili-cli"`). The `ordered_backends()` method in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) checks this variable first, placing your specified backend at the top of the probe sequence.

### Does the B站搜索 API require authentication?

No. The `_search_api_ok()` probe and subsequent search calls use Bilibili's public search endpoint (`api.bilibili.com/x/web-interface/search/all/v2`), which does not require API keys or user login credentials. However, this backend may have rate limits or reduced functionality compared to authenticated CLI tools for operations beyond basic search.