How to Add a New Platform Channel to the Agent-Reach Framework

To add a new platform channel to Agent-Reach, subclass the Channel base class in agent_reach/channels/base.py, implement the can_handle and check methods, and register the instance in the ALL_CHANNELS list within agent_reach/channels/__init__.py.

Agent-Reach is an open-source Python framework that unifies internet platform interactions through a modular channel architecture. Each supported platform—whether Twitter, YouTube, or Reddit—is implemented as a Channel that informs the core engine how to route URLs and validate dependencies. Adding a new platform channel requires implementing a concrete subclass of the abstract Channel base class and registering it with the central channel registry.

Understanding the Channel Architecture

According to the Panniantong/Agent-Reach source code, a channel is defined in agent_reach/channels/base.py as an abstract base class requiring two core methods. The can_handle method receives a URL string and returns True if the channel can process that specific domain. The check method validates whether required upstream tools—such as command-line binaries or API clients—are installed and configured, returning a tuple of (status, message) where status is one of ok, warn, off, or error.

The framework categorizes channels into three tiers. Tier 0 channels work out-of-the-box without external configuration. Tier 1 channels require free API keys or simple binaries. Tier 2 channels need complex authentication such as cookies or OAuth tokens.

Step-by-Step Implementation Guide

Step 1: Create the Channel Class

Create a new file in agent_reach/channels/ (e.g., myplatform.py) and subclass Channel from agent_reach/channels/base.py. Set the class attributes: name (string identifier), description (human-readable summary), backends (list of required binaries), and tier (integer 0, 1, or 2).

Implement can_handle(self, url: str) -> bool to parse the URL and return True for your platform's domains. Implement check(self, config=None) to verify dependencies, returning a status tuple as defined in the base class contract.

Step 2: Implement Optional Content Methods

If your platform supports reading content or searching, implement read(self, url: str) -> str and search(self, query: str) -> List[str]. These methods follow the signatures used by existing channels. Reference implementations are available in agent_reach/channels/youtube.py and agent_reach/channels/reddit.py.

Step 3: Register the Channel

Open agent_reach/channels/__init__.py and import your new class. Append an instance to the ALL_CHANNELS list. This registration makes the channel visible to the doctor diagnostic tool in agent_reach/doctor.py and the core router.

Step 4: Update CLI Documentation (Optional)

To display the new platform in agent-reach --help, modify agent_reach/cli.py where the --list-platforms option iterates over registered channels and prints their name and description attributes.

Step 5: Write Unit Tests

Create a test file in tests/ (e.g., test_myplatform_channel.py). Verify that can_handle correctly identifies URLs and that check returns appropriate statuses for installed versus missing dependencies. Follow the pattern established in tests/test_twitter_channel.py.

Step 6: Validate with the Test Suite

Run the full test suite using pytest tests/ -v to ensure the new channel integrates cleanly and no existing functionality is broken.

Complete Implementation Example

Skeleton Channel Implementation

# file: agent_reach/channels/myplatform.py

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

"""MyPlatform — read and search via `mycli`."""

import shutil
import subprocess
from .base import Channel


class MyPlatformChannel(Channel):
    name = "myplatform"
    description = "MyPlatform – articles and comments"
    backends = ["mycli"]
    tier = 1                           # requires a binary, no extra auth

    def can_handle(self, url: str) -> bool:
        from urllib.parse import urlparse
        domain = urlparse(url).netloc.lower()
        return "myplatform.com" in domain

    def check(self, config=None):
        binary = shutil.which("mycli")
        if not binary:
            return "off", "mycli 未安装。安装：pip install mycli"
        # Simple sanity check – ask the binary for its version

        try:
            r = subprocess.run([binary, "--version"], capture_output=True,
                               encoding="utf-8", timeout=5)
            if r.returncode == 0:
                return "ok", "mycli 已就绪"
        except Exception:
            pass
        return "warn", "mycli 已安装但无法运行"

    def read(self, url: str) -> str:
        """Return the article text as plain Markdown."""
        binary = shutil.which("mycli")
        r = subprocess.run([binary, "read", url], capture_output=True,
                           encoding="utf-8", timeout=15)
        return r.stdout

Registration Code

# file: agent_reach/channels/__init__.py

from .myplatform import MyPlatformChannel      # <-- add this import

ALL_CHANNELS: List[Channel] = [
    # ... existing channels ...

    MyPlatformChannel(),                       # <-- add the instance

]

Test Implementation

# file: tests/test_myplatform_channel.py

def test_myplatform_can_handle():
    from agent_reach.channels import get_channel
    ch = get_channel("myplatform")
    assert ch is not None
    assert ch.can_handle("https://myplatform.com/article/123")

def test_myplatform_check_off(monkeypatch):
    # Force shutil.which to return None → simulate missing binary

    monkeypatch.setattr("shutil.which", lambda _: None)
    ch = get_channel("myplatform")
    status, _ = ch.check()
    assert status == "off"

Channel Tiers and Doctor Integration

The check method's return value determines how the doctor report displays the channel. ok indicates full functionality, warn indicates operational but degraded status, off indicates missing dependencies, and error indicates configuration problems. The doctor script in agent_reach/doctor.py aggregates these results by iterating over ALL_CHANNELS and calling check() on each instance to inform the user of system readiness.

Summary

• Subclass Channel from agent_reach/channels/base.py and implement can_handle and check methods to define platform support and dependency validation.
• Set class attributes including name, description, backends, and tier to define channel metadata and complexity level.
• Register the channel by importing it in agent_reach/channels/__init__.py and adding it to the ALL_CHANNELS list.
• Implement optional read and search methods for content retrieval capabilities following existing channel patterns.
• Write tests in tests/ to verify URL handling and dependency checks, validating both installed and missing dependency states.
• Run pytest tests/ -v to ensure the new channel integrates cleanly with the existing Agent-Reach framework.

Frequently Asked Questions

What is the difference between can_handle and check?

The can_handle method determines if a channel can process a specific URL based on domain matching, while check verifies that external dependencies like binaries or API keys are actually installed and functional. According to the source code in agent_reach/channels/base.py, can_handle is called during URL routing, whereas check is invoked by the doctor diagnostic to report system health.

How do I handle authentication for Tier 2 platforms?

Tier 2 channels requiring authentication should implement configuration parsing in the check method, typically accepting a config parameter. The method should validate that tokens or cookie files exist and return a warn or error status if credentials are missing, mirroring the pattern used by channels that require complex authentication via stored sessions.

Can I create a channel without external dependencies?

Yes, assign tier = 0 and set backends = [] to indicate zero-configuration requirements. The check method should simply return ("ok", "Ready") since no upstream tools are needed, similar to how the WebChannel operates in the base framework as a Tier 0 implementation.

Where does the doctor command get its channel health information?

The doctor command defined in agent_reach/doctor.py iterates over the ALL_CHANNELS list from agent_reach/channels/__init__.py and calls check() on each registered instance. It aggregates the status tuples to generate the diagnostic report displayed in the CLI, showing which platforms are ready to use and which require setup.

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