How to Add a New Platform to Agent Reach Channels: A Step-by-Step Guide

To add a new platform to Agent Reach channels, subclass the Channel abstract base class, implement the can_handle and check methods, 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 acts as a thin wrapper that informs the core routing logic how to interact with specific websites and APIs. When you add a new platform, you create a Python module that conforms to the channel contract defined in the repository's architecture. This guide walks through the complete implementation process using the actual source code from the Panniantong/Agent-Reach repository.

Understanding the Channel Architecture

Before writing code, you need to understand how Agent Reach structures its platform support.

The Base Channel Class

Every channel must inherit from the Channel class defined in agent_reach/channels/base.py. This abstract base establishes the contract that the doctor check system and core router rely on to validate and route requests. The base class defines required attributes including name, description, backends, and tier, along with abstract methods that subclasses must implement.

Channel Tiers and Configuration Levels

Agent Reach organizes channels into three configuration tiers based on setup complexity:

• Tier 0 – Zero-config channels that work out-of-the-box, such as WebChannel for general HTTP requests.
• Tier 1 – Channels requiring a free API key or simple binary installation, such as TwitterChannel.
• Tier 2 – Channels needing extra setup, such as authentication via cookies or complex OAuth flows.

The check method returns a tuple (status, message) where status is one of ok, warn, off, or error. The doctor module (agent_reach/doctor.py) aggregates these results to inform users about missing dependencies or configuration issues.

Creating a New Channel Implementation

Follow these steps to add a new platform support to Agent Reach.

Step 1: Create the Channel Class File

Create a new Python file in agent_reach/channels/ for your platform. Subclass Channel and define the required class attributes:

# 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 binary installation

    
    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 not installed. Install: pip install mycli"
        try:
            r = subprocess.run([binary, "--version"], capture_output=True,
                               encoding="utf-8", timeout=5)
            if r.returncode == 0:
                return "ok", "mycli ready"
        except Exception:
            pass
        return "warn", "mycli installed but not functioning"

Step 2: Implement Content Access Methods

If your platform supports reading content or searching, implement the optional read and search methods following the signatures used by existing channels like YouTubeChannel or RedditChannel:

    def read(self, url: str) -> str:
        """Return 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 r.stdout.strip().split("\n")

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 system and the core router:

# agent_reach/channels/__init__.py

from typing import List
from .base import Channel
from .myplatform import MyPlatformChannel  # Add this import

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

    MyPlatformChannel(),  # Add this instance

]

Step 4: Update CLI Documentation (Optional)

To include your platform in the agent-reach --help output, modify agent_reach/cli.py where the --list-platforms option iterates through ALL_CHANNELS and prints Channel.name and Channel.description. The CLI automatically picks up registered channels, but you may want to add specific examples or usage notes.

Step 5: Write Unit Tests

Create a test file in the tests/ directory following the pattern of tests/test_twitter_channel.py. Verify both the can_handle URL matching logic and the check method's response to missing dependencies:

# tests/test_myplatform_channel.py

import pytest
from agent_reach.channels import get_channel


def test_myplatform_can_handle():
    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):
    # Simulate missing binary

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


def test_myplatform_check_ok(monkeypatch):
    # Simulate working binary

    class MockResult:
        returncode = 0
        stdout = "mycli 1.0.0"
    
    monkeypatch.setattr("shutil.which", lambda _: "/usr/bin/mycli")
    monkeypatch.setattr("subprocess.run", lambda *args, **kwargs: MockResult())
    
    ch = get_channel("myplatform")
    status, message = ch.check()
    assert status == "ok"

Step 6: Validate With the Test Suite

Execute the full test suite to ensure your changes do not break existing functionality:

pytest tests/ -v

All existing channel tests must continue to pass before submitting your new platform integration.

Key Files for Channel Development

When adding a new platform to Agent Reach channels, you will work primarily with these source files:

• agent_reach/channels/base.py – Defines the abstract Channel class and the interface contract including method signatures for can_handle and check.
• agent_reach/channels/__init__.py – Contains the ALL_CHANNELS registry list where you must register new channel instances.
• agent_reach/doctor.py – Runs health checks on all registered channels by calling their check methods and reporting status to users.
• agent_reach/cli.py – Command-line interface that exposes channel diagnostics and platform listing capabilities.
• agent_reach/channels/youtube.py and agent_reach/channels/reddit.py – Reference implementations showing production-ready channel classes with full read and search implementations.

Summary

Adding a new platform to Agent Reach requires implementing a standardized channel interface:

• Subclass Channel from agent_reach/channels/base.py and set the name, description, backends, and tier attributes.
• Implement can_handle(self, url: str) to identify URLs belonging to your platform.
• Implement check(self, config=None) returning a (status, message) tuple to report dependency health.
• Optionally implement read and search methods for content retrieval capabilities.
• Register the channel instance in agent_reach/channels/__init__.py by adding it to ALL_CHANNELS.
• Write tests verifying URL handling and dependency checking behaviors.
• Run pytest tests/ -v to ensure full compatibility with the existing codebase.

Frequently Asked Questions

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

You must implement can_handle(self, url: str) -> bool and check(self, config=None) in your channel subclass. The can_handle method determines if the channel can process a given URL, while check verifies that required dependencies (binaries, API keys) are installed and functional. Optional methods include read for content extraction and search for query-based URL retrieval.

How does the Agent Reach doctor verify channel dependencies?

The doctor module (agent_reach/doctor.py) iterates through all registered channels in ALL_CHANNELS and calls each channel's check method. It expects a return tuple of (status, message) where status is ok, warn, off, or error. The doctor aggregates these results to generate a health report showing which platforms are ready for use and which require configuration.

Can I add a platform that requires API keys or authentication cookies?

Yes. Set the tier class attribute to 2 for channels requiring complex authentication such as cookies, OAuth tokens, or paid API keys. In your check method, validate that the necessary credentials are present in the configuration or environment, returning "warn" or "error" status if authentication components are missing.

Where does Agent Reach maintain the list of all available channels?

The canonical registry lives in agent_reach/channels/__init__.py as the ALL_CHANNELS list, which contains instantiated channel objects. The core router imports this list to determine routing decisions, while the CLI and doctor modules use it to enumerate supported platforms and run health checks.

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