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

To add a new platform channel to Agent-Reach, subclass the abstract Channel base class in 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.

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, 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). Import the Channel base class and define your concrete subclass:

# -*- 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:

    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 to import your new class and append an instance to ALL_CHANNELS:

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:

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: Contains the abstract Channel definition and core API contract.
• agent_reach/channels/__init__.py: The registry that aggregates all channel instances used by the doctor.
• agent_reach/channels/twitter.py: Real-world example of a fully-featured channel implementation.
• agent_reach/probe.py: Helper utilities (probe_command) used by channel check() methods to test external commands.
• 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 and implement name, description, backends, tier, can_handle(), and check().
• Use probe_command: Leverage 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.
• 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 and acme_audio in acme.py), but each requires a separate import and separate instance in ALL_CHANNELS inside agent_reach/channels/__init__.py. The registry accepts any combination of classes as long as each instance inherits from the base Channel class.

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