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

You add a new platform to Agent Reach by subclassing the abstract Channel class in agent_reach/channels/base.py, implementing the can_handle and check methods to handle URL detection and backend validation, and registering the instance in the ALL_CHANNELS list within agent_reach/channels/__init__.py.

Agent Reach treats every supported internet platform as a channel, providing a consistent abstraction for content extraction across disparate services. If you need to integrate a proprietary forum, emerging social network, or specialized media host, you can add a new platform to Agent Reach by implementing a few concrete methods in a new channel module. This guide covers the exact implementation details using the Panniantong/Agent-Reach source code, from subclassing the base class to registering your integration.

Understanding the Channel Abstraction

The Base Channel Class

All platform integrations inherit from the abstract Channel class defined in agent_reach/channels/base.py. This base class defines four critical class attributes you must set: name (the channel identifier), description (human-readable summary), backends (list of external tools required), and tier (configuration complexity level where 0 = zero-config, 1 = free-key, and 2 = setup required).

Required Methods for URL Handling and Health Checks

Every new channel must implement two abstract methods. The can_handle(self, url: str) -> bool method inspects URLs and returns True when the link belongs to your platform, typically by checking the netloc via urlparse. The check(self, config=None) -> Tuple[str, str] method probes the required upstream tools, sets self.active_backend to the functional backend string, and returns a status tuple containing one of four states ("ok", "warn", "off", "error") and a descriptive message.

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

Step 1 – Create the Channel Module

Create a new Python file under agent_reach/channels/ (for example, myplatform.py). In this module, subclass Channel and implement the required methods. You can optionally add platform-specific capabilities like read, search, or transcribe methods following the patterns in agent_reach/channels/youtube.py or agent_reach/channels/reddit.py.

Here is a minimal implementation skeleton:

# agent_reach/channels/myplatform.py

from urllib.parse import urlparse
from agent_reach.probe import probe_command
from .base import Channel

class MyPlatformChannel(Channel):
    name = "myplatform"
    description = "MyPlatform – example content extraction"
    backends = ["myplatform-cli"]
    tier = 0  # Zero-config tier

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

    def check(self, config=None):
        probe = probe_command(
            "myplatform-cli", 
            ["--version"], 
            timeout=10,
            package="myplatform-cli"
        )
        
        if probe.status == "missing":
            self.active_backend = None
            return "off", "myplatform-cli not installed. Install with: pip install myplatform-cli"
        
        if probe.status == "broken":
            self.active_backend = None
            return "error", f"myplatform-cli installed but cannot run:\n{probe.hint}"
        
        self.active_backend = "myplatform-cli"
        return "ok", "myplatform-cli is ready"

Step 2 – Register the Channel

After creating the module, expose it to the framework by editing agent_reach/channels/__init__.py. Import your new class and append an instance to the ALL_CHANNELS list:

# agent_reach/channels/__init__.py

from typing import List
from .base import Channel
from .myplatform import MyPlatformChannel  # New import

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

    MyPlatformChannel(),  # New instance

]

The registration order is irrelevant; the registry is used by the doctor diagnostic command and by the core routing logic in agent_reach/core.py to match URLs to channels.

Step 3 – Expose Configuration (If Required)

If your platform requires API keys, authentication cookies, or other settings, extend agent_reach/config.py with appropriate is_configured checks following the pattern used by existing channels. For example, YouTube's Whisper provider checks configuration validity around lines 68-78 of the config file. Ensure your check method returns the appropriate status strings so the doctor command can accurately report channel health.

Testing Your New Integration

Once implemented, verify your channel using the built-in diagnostic tool and functional tests:

# Verify the channel is recognized and healthy

python -m agent_reach.cli doctor

# Expected output: myplatform: ok – myplatform-cli is ready

Test the full integration by calling the core read function:

from agent_reach.core import read

url = "https://myplatform.com/some/content"
content = read(url)  # Dispatches to MyPlatformChannel.read()

print(content)

If your channel supports multiple backends, implement logic in check() to select the best available option, storing the choice in self.active_backend. The base class provides self.ordered_backends() to iterate through your backends list in priority order.

Summary

• Subclass Channel from agent_reach/channels/base.py and set the name, description, backends, and tier class attributes.
• Implement can_handle to identify your platform's URLs by domain or pattern.
• Implement check to probe external dependencies and return status tuples ("ok", "warn", "off", "error").
• Register the instance in agent_reach/channels/__init__.py by adding it to the ALL_CHANNELS list.
• Extend configuration in agent_reach/config.py if your channel requires API keys or authentication.

Frequently Asked Questions

What is the difference between tier 0, tier 1, and tier 2 channels?

Tier 0 channels require zero configuration and work immediately after installation. Tier 1 channels need a free API key or simple token that users must provide. Tier 2 channels require complex setup, paid credentials, or additional infrastructure. Set the tier class attribute accordingly to help users understand the integration complexity when they run the doctor command.

How does Agent Reach route URLs to the correct channel?

The routing logic in agent_reach/core.py iterates through the ALL_CHANNELS registry and calls each channel's can_handle method against the provided URL. The first channel returning True receives the read, search, or transcribe call. This is why precise URL matching in can_handle is critical to avoid intercepting links meant for other platforms.

Can I implement multiple backends for a single platform?

Yes. Define multiple entries in the backends list class attribute, then iterate through self.ordered_backends() inside your check method. Store the first working backend name in self.active_backend. This pattern allows graceful fallbacks when primary tools are missing, as demonstrated in agent_reach/channels/reddit.py.

Where should I add API key validation for my new channel?

Add configuration schema and validation logic in agent_reach/config.py following the existing pattern used by YouTube's Whisper integration. Your channel's check method should then reference these configuration values to validate credentials before returning "ok" status, ensuring the doctor command accurately reports missing or invalid API keys.

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