# How to Add New Platform Channels to the Agent-Reach Channel Registry

> Learn how to add new platform channels to Agent-Reach. Subclass the Channel base class, implement methods, and register your channel in the registry for enhanced functionality.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-11

---

**To add a new platform channel to Agent-Reach, subclass the abstract `Channel` base class in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), implement the required methods (`can_handle`, `check`), and register the instance in the `ALL_CHANNELS` list inside [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py).**

Agent-Reach discovers and reports the health of upstream tools through a channel abstraction that maps platform URLs to executable back-ends. Extending the channel registry allows you to integrate new internet platforms—such as video hosts, social networks, or search engines—into the unified doctor health-check system. This guide covers the exact implementation steps required to add new platform channels to the Agent-Reach channel registry while maintaining compatibility with the existing architecture.

## Understanding the Channel Abstraction

The channel system in Agent-Reach relies on a strict contract defined in the base class. Each platform is represented by a concrete subclass that provides metadata and health-check capabilities.

### The Channel Base Class

In [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), the abstract `Channel` class defines the interface that every platform must implement. This file contains the core API contract that ensures consistency across all supported platforms, from Twitter to YouTube.

### Required Attributes and Methods

Every concrete channel must provide the following attributes and methods:

- **`name`**: Short identifier used on the CLI (e.g., `"twitter"`).
- **`description`**: Human-readable description displayed in the doctor report.
- **`backends`**: Ordered list of candidate back-end commands or tools (e.g., `["twitter-cli", "OpenCLI"]`).
- **`tier`**: Configuration complexity level (0 = zero-config, 1 = free API key, 2 = requires setup).
- **`can_handle(url)`**: Returns `True` when the supplied URL belongs to the platform.
- **`check(config)`**: Probes the back-ends, sets `self.active_backend`, and returns a `(status, message)` tuple where `status` is one of `ok`, `warn`, `error`, or `off`.

## Step-by-Step Implementation Guide

Follow these steps to add a new platform channel to the registry.

### Step 1: Create the Channel Module

Create a new Python file in `agent_reach/channels/` (e.g., [`acme_video.py`](https://github.com/Panniantong/Agent-Reach/blob/main/acme_video.py)). Import the `Channel` base class and define your concrete subclass:

```python

# -*- coding: utf-8 -*-

"""AcmeVideo – health check for the Acme video platform."""

from .base import Channel
from agent_reach.probe import probe_command


class AcmeVideoChannel(Channel):
    name = "acme_video"
    description = "AcmeVideo 视频与字幕"
    backends = ["acme-cli"]
    tier = 1

```

### Step 2: Implement Required Methods

Implement the `can_handle` method to identify platform URLs and the `check` method to verify back-end health:

```python
    def can_handle(self, url: str) -> bool:
        """Accept URLs that contain the acmevideo.com domain."""
        from urllib.parse import urlparse

        return "acmevideo.com" in urlparse(url).netloc.lower()

    def check(self, config=None):
        """Probe the `acme-cli` command; report status."""
        self.active_backend = None
        probe = probe_command(
            "acme-cli",
            ["status"],
            timeout=15,
            retries=1,
            package="acme-cli",
        )
        if probe.status == "missing":
            return "warn", (
                "Acme CLI 未安装。安装方式：\n"
                "  pipx install acme-cli"
            )
        if probe.status == "broken":
            return "error", f"Acme CLI 可执行但出错。\n{probe.hint}"
        if probe.ok and "ready: true" in probe.output:
            self.active_backend = "acme-cli"
            return "ok", "Acme CLI 可用（搜索、读取视频）。"
        return "warn", "Acme CLI 已安装但未准备好，请检查登录状态或配置。"

```

### Step 3: Register in the Channel Registry

Edit [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) to import your new class and append an instance to `ALL_CHANNELS`:

```python
from .acme_video import AcmeVideoChannel   # <-- new import

ALL_CHANNELS: List[Channel] = [
    GitHubChannel(),
    TwitterChannel(),
    YouTubeChannel(),
    RedditChannel(),
    BilibiliChannel(),
    XiaoHongShuChannel(),
    LinkedInChannel(),
    XiaoyuzhouChannel(),
    V2EXChannel(),
    XueqiuChannel(),
    RSSChannel(),
    ExaSearchChannel(),
    WebChannel(),
    AcmeVideoChannel(),                     # <-- new instance

]

```

## Verification and Testing

After registering the channel, run the doctor command to verify your implementation:

```bash
python -m agent_reach.cli doctor

```

If the `acme-cli` executable is present and healthy, the output includes:

```

acme_video: ok – Acme CLI 可用（搜索、读取视频）。

```

If the command is missing, the doctor displays the warning message and installation hint defined in your `check()` method.

## Key Files and References

Understanding these source files helps when adding new platform channels:

- **[`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py)**: Contains the abstract `Channel` definition and core API contract.
- **[`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py)**: The registry that aggregates all channel instances used by the doctor.
- **[`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py)**: Real-world example of a fully-featured channel implementation.
- **[`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py)**: Helper utilities (`probe_command`) used by channel `check()` methods to test external commands.
- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)**: Orchestrates health checks by iterating over `ALL_CHANNELS`.

## Summary

- **Subclass `Channel`**: Inherit from the abstract base class in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) and implement `name`, `description`, `backends`, `tier`, `can_handle()`, and `check()`.
- **Use `probe_command`**: Leverage [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) utilities to test external CLI tools and return standardized status tuples.
- **Register in `ALL_CHANNELS`**: Import your class and append an instance to the list in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py).
- **Test with doctor**: Run `python -m agent_reach.cli doctor` to verify the new channel appears in health reports with correct status.

## Frequently Asked Questions

### What is the purpose of the `tier` attribute in Agent-Reach channels?

The `tier` attribute indicates configuration complexity for end-users. **Tier 0** requires zero configuration, **Tier 1** needs a free API key, and **Tier 2** demands additional setup such as authentication flows or paid credentials. This helps users quickly understand the effort required to activate a particular platform integration.

### How does the `can_handle` method determine URL ownership?

The `can_handle` method implements platform-specific URL detection logic. As shown in the AcmeVideo example, it typically parses the URL using `urllib.parse.urlparse` and checks if the netloc matches the platform's domain. Return `True` only when the URL definitively belongs to your platform to avoid conflicts with other channels.

### Why must I set `self.active_backend` in the `check` method?

Agent-Reach uses `self.active_backend` to track which back-end command is currently functional for the platform. The doctor command reads this value after `check()` completes to report which specific tool is active. If no back-end responds correctly, leave the value as `None` to indicate the channel is unavailable.

### Can I register multiple channels in a single module?

Yes, you can define multiple channel classes in one Python file (e.g., [`acme_video.py`](https://github.com/Panniantong/Agent-Reach/blob/main/acme_video.py) and `acme_audio` in [`acme.py`](https://github.com/Panniantong/Agent-Reach/blob/main/acme.py)), but each requires a separate import and separate instance in `ALL_CHANNELS` inside [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py). The registry accepts any combination of classes as long as each instance inherits from the base `Channel` class.