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

> Learn how to add a new platform to Agent Reach by subclassing Channel implementing can_handle and check methods and registering your channel.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-04

---

**You add a new platform to Agent Reach by subclassing the abstract `Channel` class in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) or [`agent_reach/channels/reddit.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/reddit.py).

Here is a minimal implementation skeleton:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py). Import your new class and append an instance to the `ALL_CHANNELS` list:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash

# 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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) by adding it to the `ALL_CHANNELS` list.
- **Extend configuration** in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.