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

To add a new platform channel to Agent Reach, subclass the Channel abstract class defined 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 routing framework that treats every supported internet platform as a Channel. Each channel acts as a thin wrapper telling the core engine how to validate URLs and verify dependencies. Whether you are integrating a niche forum or a mainstream social network, the architecture remains consistent across the codebase.

Understanding the Channel Architecture

The Channel abstract base class in agent_reach/channels/base.py defines the contract that every platform must follow. At minimum, a channel must implement two critical methods:

• can_handle(self, url: str) -> bool: Returns True if the channel recognizes the domain or URL pattern as its own.
• check(self, config=None): Returns a tuple (status, message) where status is one of ok, warn, off, or error, verifying that required binaries or API keys are present.

Channels also expose metadata attributes that the doctor and CLI use for diagnostics:

• name: Short identifier used in logs and CLI output.
• description: Human-readable explanation of the platform.
• backends: List of external tools or binaries required (e.g., ["yt-dlp"]).
• tier: Integer indicating setup complexity. Tier 0 works out-of-the-box, Tier 1 requires a free API key or simple binary, and Tier 2 needs complex authentication such as cookies.

Step-by-Step Implementation Guide

Step 1: Create the Channel Class

Create a new file in agent_reach/channels/ (e.g., myplatform.py). Subclass Channel and define the required attributes and methods.

# agent_reach/channels/myplatform.py

import shutil
import subprocess
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 is 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 is ready"
        except Exception:
            pass
        return "warn", "mycli is installed but not functioning"

Step 2: Implement Optional Methods

If your platform supports content retrieval or search, implement the optional interface methods following the signatures found in agent_reach/channels/youtube.py and reddit.py:

• read(self, url: str) -> str: Fetches content and returns plain Markdown text.
• search(self, query: str) -> List[str]: Returns a list of result URLs.

    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

Step 3: Register the Channel

Open agent_reach/channels/__init__.py and import your new class. Append an instance to the ALL_CHANNELS list so the doctor check and core router can discover it.

# agent_reach/channels/__init__.py

from .myplatform import MyPlatformChannel  # Add this import

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

    MyPlatformChannel(),  # Add this instance

]

Step 4: Update CLI Documentation (Optional)

To expose the new platform in agent-reach --help output, modify agent_reach/cli.py where the --list-platforms option iterates over Channel.name and Channel.description.

Step 5: Write Tests

Create a test file in tests/ (e.g., test_myplatform_channel.py) following the pattern in tests/test_twitter_channel.py. Verify both the can_handle logic and the check response for missing dependencies.

# 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):
    # 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 integration does not break existing functionality:

pytest tests/ -v

Key Files and Their Roles

• agent_reach/channels/base.py: Defines the abstract Channel class and the check contract that all platforms must implement.
• agent_reach/channels/__init__.py: Contains the ALL_CHANNELS registry that the doctor and router use to discover available platforms.
• agent_reach/channels/<platform>.py: Concrete implementations (e.g., twitter.py, youtube.py) that serve as reference patterns.
• agent_reach/doctor.py: Aggregates check results from all registered channels to report system health to the user.
• agent_reach/cli.py: Command-line entry point that consumes the channel registry for diagnostics and platform listing.

Summary

• Subclass Channel from agent_reach/channels/base.py to define how your platform identifies URLs and validates dependencies.
• Implement can_handle to route URLs correctly and check to report installation status via the doctor.
• Register the instance in agent_reach/channels/__init__.py by adding it to ALL_CHANNELS.
• Follow tier conventions: 0 for zero-config, 1 for binaries/API keys, 2 for complex authentication.
• Test thoroughly using pytest to verify behavior when dependencies are both present and missing.

Frequently Asked Questions

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

You must implement can_handle(self, url: str) and check(self, config=None). The can_handle method enables the router to delegate URLs to your channel, while check allows agent_reach/doctor.py to verify that required binaries or credentials are installed. Optional methods like read and search only need implementation if your platform supports content retrieval.

How does Agent Reach determine if a channel can handle a specific URL?

The core router iterates through ALL_CHANNELS in agent_reach/channels/__init__.py and calls can_handle(url) on each instance. The first channel returning True receives the request. This logic is separate from the check method, which validates runtime dependencies rather than routing capabilities.

What are channel tiers in Agent Reach?

Tiers classify setup complexity. Tier 0 channels require no configuration (e.g., WebChannel). Tier 1 channels need a free API key or simple binary installation. Tier 2 channels demand extra setup such as authentication cookies or OAuth flows. The tier attribute helps the doctor prioritize which missing dependencies to report first.

How do I troubleshoot a new channel that isn't being recognized?

First, verify that your class is imported and instantiated in agent_reach/channels/__init__.py within the ALL_CHANNELS list. Run agent-reach --list-platforms (or check the relevant output in agent_reach/cli.py) to confirm the name and description appear. If the channel is listed but fails to route URLs, debug your can_handle implementation. If the doctor reports it as off, inspect the check method and ensure the binary or API key is in your system PATH.

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