How to Add a New Platform Channel to Agent Reach: A Complete Developer Guide

To add a new platform channel to Agent Reach, subclass the Channel base class defined in agent_reach/channels/base.py, implement the required can_handle and check methods, optionally add content retrieval methods like read or search, and register the instance in the ALL_CHANNELS list within agent_reach/channels/__init__.py.

Agent Reach treats every supported internet platform as a Channel, which is a thin wrapper that tells the core routing logic how to handleURLs and verify dependencies. This guide walks you through the exact implementation steps used in the Panniantong/Agent-Reach repository to extend the tool with new platform support.

Understanding the Channel Architecture

A channel in Agent Reach is an abstraction that encapsulates platform-specific logic. Each channel must implement at least two critical methods:

• can_handle(self, url: str) -> bool: Determines if this channel should process a given URL based on domain or pattern matching.
• check(self, config=None): Verifies that required upstream tools (binaries, API keys, or authentication) are installed and configured, returning a tuple of (status, message) where status is one of ok, warn, off, or error.

Channels are organized into tiers based on setup complexity:

• Tier 0: Zero-configuration channels that work out-of-the-box (e.g., WebChannel).
• Tier 1: Require a free API key or simple binary installation (e.g., TwitterChannel).
• Tier 2: Need extra setup like cookie-based authentication.

Step-by-Step Implementation

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. Define the class attributes and implement the required methods:

# file: agent_reach/channels/myplatform.py

import shutil
import subprocess
from typing import List
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"
        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 已安装但无法运行"

Step 2: Implement Optional Content Methods

If your platform supports reading content or searching, implement these additional methods following the signatures found in existing channels like agent_reach/channels/youtube.py and agent_reach/channels/reddit.py:

    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

    def search(self, query: str) -> List[str]:
        """Return list of URLs matching the query."""
        binary = shutil.which("mycli")
        r = subprocess.run([binary, "search", query], capture_output=True,
                           encoding="utf-8", timeout=15)
        return [line.strip() for line in r.stdout.splitlines() if line.strip()]

Step 3: Register the Channel

Import your new class in agent_reach/channels/__init__.py and add an instance to the ALL_CHANNELS list. This registration makes the channel visible to the doctor check and the core router:

# file: agent_reach/channels/__init__.py

from .myplatform import MyPlatformChannel  # <-- add import

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

    MyPlatformChannel(),  # <-- add instance

]

Step 4: Update CLI Documentation (Optional)

If you want the new platform to appear in agent-reach --help output or in the --list-platforms option, update agent_reach/cli.py to reference your channel's name and description attributes.

Step 5: Write Tests

Create a test file following the pattern in tests/test_twitter_channel.py to verify your 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")
    assert not ch.can_handle("https://other-site.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"

Step 6: Validate with the Test Suite

Run the full test suite to ensure your changes don't break existing functionality:

pytest tests/ -v

Key Integration Points

Doctor Integration: The check method results are aggregated by agent_reach/doctor.py, which runs check on all registered channels and reports missing dependencies to the user. Ensure your check implementation returns precise status codes so users receive actionable feedback.

Router Visibility: The core routing logic uses ALL_CHANNELS from agent_reach/channels/__init__.py to determine which channel handles a given URL. Registration is mandatory for the channel to function within the Agent Reach workflow.

Summary

• Subclass Channel from agent_reach/channels/base.py and set name, description, backends, and tier attributes.
• Implement can_handle to match your platform's URL patterns and check to verify dependencies.
• Add read/search methods if your platform supports content retrieval, matching signatures from existing implementations like youtube.py.
• Register in ALL_CHANNELS within agent_reach/channels/__init__.py to activate the channel.
• Write tests in tests/test_channels.py or dedicated files to verify URL handling and dependency checking.
• Run pytest to validate the integration before submitting.

Frequently Asked Questions

What methods are required when adding a new platform channel to Agent Reach?

You must implement can_handle(self, url: str) -> bool and check(self, config=None). The can_handle method determines if your channel should process a URL, while check verifies that required tools or credentials are available. Optional methods like read and search only need implementation if your platform supports content retrieval.

How does the tier system work in Agent Reach channels?

The tier attribute indicates setup complexity: Tier 0 requires zero configuration, Tier 1 needs a free API key or simple binary (like mycli), and Tier 2 requires complex authentication such as cookie-based sessions. Set this appropriately in your channel class to help users understand deployment requirements.

What is the purpose of the check method in Agent Reach channels?

The check method validates that external dependencies (binaries, libraries, or credentials) required by your platform are installed and functional. It returns a tuple (status, message) where status is ok, warn, off, or error. This feeds into agent_reach/doctor.py to provide users with diagnostic information about which platforms are ready to use.

Where are platform channels registered in the Agent Reach codebase?

All platform channels are registered in agent_reach/channels/__init__.py by importing the channel class and appending an instance to the ALL_CHANNELS list. This list is consumed by the doctor utility and the core router to discover available platforms at runtime.

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