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

> Learn how to add a new platform to Agent Reach channels. Follow this step by step guide to subclass Channel, implement methods, and register your new channel.

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

---

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

```python

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

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

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_twitter_channel.py). Verify both the `can_handle` URL matching logic and the `check` method's response to missing dependencies:

```python

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

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py)** – Contains the `ALL_CHANNELS` registry list where you must register new channel instances.
- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – Command-line interface that exposes channel diagnostics and platform listing capabilities.
- **[`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py)** and **[`agent_reach/channels/reddit.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.