# How to Add a New Platform Channel to the Agent-Reach Framework

> Learn to add a new platform channel to the Agent-Reach framework by subclassing Channel, implementing key methods, and registering your new channel in the ALL_CHANNELS list.

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

---

**To add a new platform channel to Agent-Reach, subclass the `Channel` base class in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py).**

Agent-Reach is an open-source Python framework that unifies internet platform interactions through a modular channel architecture. Each supported platform—whether Twitter, YouTube, or Reddit—is implemented as a **Channel** that informs the core engine how to route URLs and validate dependencies. Adding a new platform channel requires implementing a concrete subclass of the abstract `Channel` base class and registering it with the central channel registry.

## Understanding the Channel Architecture

According to the Panniantong/Agent-Reach source code, a channel is defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) as an abstract base class requiring two core methods. The **`can_handle`** method receives a URL string and returns `True` if the channel can process that specific domain. The **`check`** method validates whether required upstream tools—such as command-line binaries or API clients—are installed and configured, returning a tuple of `(status, message)` where status is one of `ok`, `warn`, `off`, or `error`.

The framework categorizes channels into three **tiers**. **Tier 0** channels work out-of-the-box without external configuration. **Tier 1** channels require free API keys or simple binaries. **Tier 2** channels need complex authentication such as cookies or OAuth tokens.

## Step-by-Step Implementation Guide

### Step 1: Create the Channel Class

Create a new file in `agent_reach/channels/` (e.g., [`myplatform.py`](https://github.com/Panniantong/Agent-Reach/blob/main/myplatform.py)) and subclass `Channel` from [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py). Set the class attributes: `name` (string identifier), `description` (human-readable summary), `backends` (list of required binaries), and `tier` (integer 0, 1, or 2).

Implement `can_handle(self, url: str) -> bool` to parse the URL and return `True` for your platform's domains. Implement `check(self, config=None)` to verify dependencies, returning a status tuple as defined in the base class contract.

### Step 2: Implement Optional Content Methods

If your platform supports reading content or searching, implement **`read(self, url: str) -> str`** and **`search(self, query: str) -> List[str]`**. These methods follow the signatures used by existing channels. Reference implementations are available in [`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).

### Step 3: Register the Channel

Open [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) and import your new class. Append an instance to the **`ALL_CHANNELS`** list. This registration makes the channel visible to the doctor diagnostic tool in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) and the core router.

### Step 4: Update CLI Documentation (Optional)

To display the new platform in `agent-reach --help`, modify [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) where the `--list-platforms` option iterates over registered channels and prints their `name` and `description` attributes.

### Step 5: Write Unit Tests

Create a test file in `tests/` (e.g., [`test_myplatform_channel.py`](https://github.com/Panniantong/Agent-Reach/blob/main/test_myplatform_channel.py)). Verify that `can_handle` correctly identifies URLs and that `check` returns appropriate statuses for installed versus missing dependencies. Follow the pattern established in [`tests/test_twitter_channel.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_twitter_channel.py).

### Step 6: Validate with the Test Suite

Run the full test suite using `pytest tests/ -v` to ensure the new channel integrates cleanly and no existing functionality is broken.

## Complete Implementation Example

### Skeleton Channel Implementation

```python

# file: agent_reach/channels/myplatform.py

# -*- coding: utf-8 -*-

"""MyPlatform — read and search via `mycli`."""

import shutil
import subprocess
from .base import Channel


class MyPlatformChannel(Channel):
    name = "myplatform"
    description = "MyPlatform – articles and comments"
    backends = ["mycli"]
    tier = 1                           # requires a binary, no extra auth

    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 未安装。安装：pip install mycli"
        # Simple sanity check – ask the binary for its version

        try:
            r = subprocess.run([binary, "--version"], capture_output=True,
                               encoding="utf-8", timeout=5)
            if r.returncode == 0:
                return "ok", "mycli 已就绪"
        except Exception:
            pass
        return "warn", "mycli 已安装但无法运行"

    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

```

### Registration Code

```python

# file: agent_reach/channels/__init__.py

from .myplatform import MyPlatformChannel      # <-- add this import

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

    MyPlatformChannel(),                       # <-- add the instance

]

```

### Test Implementation

```python

# file: 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):
    # Force shutil.which to return None → simulate missing binary

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

```

## Channel Tiers and Doctor Integration

The **`check`** method's return value determines how the doctor report displays the channel. **`ok`** indicates full functionality, **`warn`** indicates operational but degraded status, **`off`** indicates missing dependencies, and **`error`** indicates configuration problems. The doctor script in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) aggregates these results by iterating over `ALL_CHANNELS` and calling `check()` on each instance to inform the user of system readiness.

## Summary

- Subclass `Channel` from [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) and implement `can_handle` and `check` methods to define platform support and dependency validation.
- Set class attributes including `name`, `description`, `backends`, and `tier` to define channel metadata and complexity level.
- Register the channel by importing it in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) and adding it to the `ALL_CHANNELS` list.
- Implement optional `read` and `search` methods for content retrieval capabilities following existing channel patterns.
- Write tests in `tests/` to verify URL handling and dependency checks, validating both installed and missing dependency states.
- Run `pytest tests/ -v` to ensure the new channel integrates cleanly with the existing Agent-Reach framework.

## Frequently Asked Questions

### What is the difference between `can_handle` and `check`?

The `can_handle` method determines if a channel can process a specific URL based on domain matching, while `check` verifies that external dependencies like binaries or API keys are actually installed and functional. According to the source code in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), `can_handle` is called during URL routing, whereas `check` is invoked by the doctor diagnostic to report system health.

### How do I handle authentication for Tier 2 platforms?

Tier 2 channels requiring authentication should implement configuration parsing in the `check` method, typically accepting a `config` parameter. The method should validate that tokens or cookie files exist and return a `warn` or `error` status if credentials are missing, mirroring the pattern used by channels that require complex authentication via stored sessions.

### Can I create a channel without external dependencies?

Yes, assign `tier = 0` and set `backends = []` to indicate zero-configuration requirements. The `check` method should simply return `("ok", "Ready")` since no upstream tools are needed, similar to how the `WebChannel` operates in the base framework as a Tier 0 implementation.

### Where does the `doctor` command get its channel health information?

The doctor command defined in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) iterates over the `ALL_CHANNELS` list from [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) and calls `check()` on each registered instance. It aggregates the status tuples to generate the diagnostic report displayed in the CLI, showing which platforms are ready to use and which require setup.