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

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

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

---

**To add a new platform channel to Agent Reach, subclass the `Channel` abstract class defined 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 routing framework that treats every supported internet platform as a **Channel**. Each channel acts as a thin wrapper telling the core engine how to validate URLs and verify dependencies. Whether you are integrating a niche forum or a mainstream social network, the architecture remains consistent across the codebase.

## Understanding the Channel Architecture

The `Channel` abstract base class in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) defines the contract that every platform must follow. At minimum, a channel must implement two critical methods:

- **`can_handle(self, url: str) -> bool`**: Returns `True` if the channel recognizes the domain or URL pattern as its own.
- **`check(self, config=None)`**: Returns a tuple `(status, message)` where `status` is one of `ok`, `warn`, `off`, or `error`, verifying that required binaries or API keys are present.

Channels also expose metadata attributes that the doctor and CLI use for diagnostics:

- **`name`**: Short identifier used in logs and CLI output.
- **`description`**: Human-readable explanation of the platform.
- **`backends`**: List of external tools or binaries required (e.g., `["yt-dlp"]`).
- **`tier`**: Integer indicating setup complexity. **Tier 0** works out-of-the-box, **Tier 1** requires a free API key or simple binary, and **Tier 2** needs complex authentication such as cookies.

## 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)). Subclass `Channel` and define the required attributes and methods.

```python

# agent_reach/channels/myplatform.py

import shutil
import subprocess
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 is 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 is ready"
        except Exception:
            pass
        return "warn", "mycli is installed but not functioning"

```

### Step 2: Implement Optional Methods

If your platform supports content retrieval or search, implement the optional interface methods following the signatures found in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) and [`reddit.py`](https://github.com/Panniantong/Agent-Reach/blob/main/reddit.py):

- **`read(self, url: str) -> str`**: Fetches content and returns plain Markdown text.
- **`search(self, query: str) -> List[str]`**: Returns a list of result URLs.

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

```

### 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 so the doctor check and core router can discover it.

```python

# agent_reach/channels/__init__.py

from .myplatform import MyPlatformChannel  # Add this import

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

    MyPlatformChannel(),  # Add this instance

]

```

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

To expose the new platform in `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 over `Channel.name` and `Channel.description`.

### Step 5: Write 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)) following the pattern in [`tests/test_twitter_channel.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_twitter_channel.py). Verify both the `can_handle` logic and the `check` response for missing dependencies.

```python

# 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):
    # 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 integration does not break existing functionality:

```bash
pytest tests/ -v

```

## Key Files and Their Roles

- **[`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 `check` contract that all platforms must implement.
- **[`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py)**: Contains the `ALL_CHANNELS` registry that the doctor and router use to discover available platforms.
- **`agent_reach/channels/<platform>.py`**: Concrete implementations (e.g., [`twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/twitter.py), [`youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/youtube.py)) that serve as reference patterns.
- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)**: Aggregates `check` results from all registered channels to report system health to the user.
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**: Command-line entry point that consumes the channel registry for diagnostics and platform listing.

## Summary

- **Subclass `Channel`** from [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) to define how your platform identifies URLs and validates dependencies.
- **Implement `can_handle`** to route URLs correctly and **`check`** to report installation status via the doctor.
- **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 `ALL_CHANNELS`.
- **Follow tier conventions**: 0 for zero-config, 1 for binaries/API keys, 2 for complex authentication.
- **Test thoroughly** using `pytest` to verify behavior when dependencies are both present and missing.

## Frequently Asked Questions

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

You must implement **`can_handle(self, url: str)`** and **`check(self, config=None)`**. The `can_handle` method enables the router to delegate URLs to your channel, while `check` allows [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) to verify that required binaries or credentials are installed. Optional methods like `read` and `search` only need implementation if your platform supports content retrieval.

### How does Agent Reach determine if a channel can handle a specific URL?

The core router iterates through `ALL_CHANNELS` in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) and calls **`can_handle(url)`** on each instance. The first channel returning `True` receives the request. This logic is separate from the `check` method, which validates runtime dependencies rather than routing capabilities.

### What are channel tiers in Agent Reach?

Tiers classify setup complexity. **Tier 0** channels require no configuration (e.g., `WebChannel`). **Tier 1** channels need a free API key or simple binary installation. **Tier 2** channels demand extra setup such as authentication cookies or OAuth flows. The `tier` attribute helps the doctor prioritize which missing dependencies to report first.

### How do I troubleshoot a new channel that isn't being recognized?

First, verify that your class is imported and instantiated in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) within the `ALL_CHANNELS` list. Run `agent-reach --list-platforms` (or check the relevant output in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) to confirm the `name` and `description` appear. If the channel is listed but fails to route URLs, debug your `can_handle` implementation. If the doctor reports it as `off`, inspect the `check` method and ensure the binary or API key is in your system `PATH`.