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

> Learn how to add a new platform channel to Agent Reach by subclassing the Channel base class. Follow this developer guide to implement essential methods and register your new channel.

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

---

**To add a new platform channel to Agent Reach, subclass the `Channel` base class defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), implement the required `can_handle` and `check` methods, optionally add content retrieval methods like `read` or `search`, 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 is a thin wrapper that tells the core routing logic how to handleURLs and verify dependencies. This guide walks you through the exact implementation steps used in the Panniantong/Agent-Reach repository to extend the tool with new platform support.

## Understanding the Channel Architecture

A **channel** in Agent Reach is an abstraction that encapsulates platform-specific logic. Each channel must implement at least two critical methods:

- **`can_handle(self, url: str) -> bool`**: Determines if this channel should process a given URL based on domain or pattern matching.
- **`check(self, config=None)`**: Verifies that required upstream tools (binaries, API keys, or authentication) are installed and configured, returning a tuple of `(status, message)` where status is one of `ok`, `warn`, `off`, or `error`.

Channels are organized into **tiers** based on setup complexity:
- **Tier 0**: Zero-configuration channels that work out-of-the-box (e.g., `WebChannel`).
- **Tier 1**: Require a free API key or simple binary installation (e.g., `TwitterChannel`).
- **Tier 2**: Need extra setup like cookie-based authentication.

## Step-by-Step Implementation

### 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). Define the class attributes and implement the required methods:

```python

# file: 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 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"
        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 已安装但无法运行"

```

### Step 2: Implement Optional Content Methods

If your platform supports reading content or searching, implement these additional methods following the signatures found in existing channels like [`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):

```python
    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

    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 [line.strip() for line in r.stdout.splitlines() if line.strip()]

```

### 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 and the core router:

```python

# file: agent_reach/channels/__init__.py

from .myplatform import MyPlatformChannel  # <-- add import

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

    MyPlatformChannel(),  # <-- add instance

]

```

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

If you want the new platform to appear in `agent-reach --help` output or in the `--list-platforms` option, update [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) to reference your channel's `name` and `description` attributes.

### Step 5: Write Tests

Create a test file following the pattern in [`tests/test_twitter_channel.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_twitter_channel.py) to verify your 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")
    assert not ch.can_handle("https://other-site.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"

```

### Step 6: Validate with the Test Suite

Run the full test suite to ensure your changes don't break existing functionality:

```bash
pytest tests/ -v

```

## Key Integration Points

**Doctor Integration**: The `check` method results are aggregated by [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), which runs `check` on all registered channels and reports missing dependencies to the user. Ensure your `check` implementation returns precise status codes so users receive actionable feedback.

**Router Visibility**: The core routing logic uses `ALL_CHANNELS` from [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) to determine which channel handles a given URL. Registration is mandatory for the channel to function within the Agent Reach workflow.

## Summary

- **Subclass `Channel`** from [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) and set `name`, `description`, `backends`, and `tier` attributes.
- **Implement `can_handle`** to match your platform's URL patterns and **`check`** to verify dependencies.
- **Add `read`/`search` methods** if your platform supports content retrieval, matching signatures from existing implementations like [`youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/youtube.py).
- **Register in `ALL_CHANNELS`** within [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) to activate the channel.
- **Write tests** in [`tests/test_channels.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_channels.py) or dedicated files to verify URL handling and dependency checking.
- **Run `pytest`** to validate the integration before submitting.

## Frequently Asked Questions

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

You must implement **`can_handle(self, url: str) -> bool`** and **`check(self, config=None)`**. The `can_handle` method determines if your channel should process a URL, while `check` verifies that required tools or credentials are available. Optional methods like `read` and `search` only need implementation if your platform supports content retrieval.

### How does the tier system work in Agent Reach channels?

The **tier** attribute indicates setup complexity: **Tier 0** requires zero configuration, **Tier 1** needs a free API key or simple binary (like `mycli`), and **Tier 2** requires complex authentication such as cookie-based sessions. Set this appropriately in your channel class to help users understand deployment requirements.

### What is the purpose of the check method in Agent Reach channels?

The **`check` method** validates that external dependencies (binaries, libraries, or credentials) required by your platform are installed and functional. It returns a tuple `(status, message)` where status is `ok`, `warn`, `off`, or `error`. This feeds into [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) to provide users with diagnostic information about which platforms are ready to use.

### Where are platform channels registered in the Agent Reach codebase?

All platform channels are registered in **[`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py)** by importing the channel class and appending an instance to the **`ALL_CHANNELS`** list. This list is consumed by the doctor utility and the core router to discover available platforms at runtime.