# How to Add a Custom Channel for a New Platform in Agent Reach

> Learn to add a custom channel for a new platform in Agent Reach. Subclass Channel, implement required methods, and register it for seamless integration.

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

---

**To add a custom channel for a new platform in Agent Reach, subclass `Channel` in a new file under `agent_reach/channels/`, implement the required attributes and methods, and register the instance in the `ALL_CHANNELS` list inside [`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*. Adding a custom channel for a new platform requires no changes to the core router or CLI logic; you only need to implement the abstract contract defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) and expose your class through the global registry.

## Create a Channel Subclass

Start by adding a new Python module under `agent_reach/channels/`. For example, [`agent_reach/channels/myplatform.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/myplatform.py). Inside this file, import `Channel` from `.base` and create a concrete subclass.

### Define Mandatory Attributes

Every channel must declare four class-level attributes that the CLI and doctor command read at runtime:

- **`name`** — A short string identifier used on the CLI (for example, `"myplatform"`).
- **`description`** — A human-readable summary of the platform.
- **`backends`** — A list of external tools required by the channel (for example, `["mytool"]`). Leave this empty if no external binary is needed.
- **`tier`** — An integer indicating setup complexity: `0` for zero-config, `1` for a free API key, or `2` for full manual setup.

### Implement `can_handle`

The `can_handle(self, url: str) -> bool` method is the routing gate. It receives a candidate URL and must return `True` when the hostname or path pattern matches your platform. The core router in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) iterates over `ALL_CHANNELS` and delegates the URL to the first channel whose `can_handle` returns `True`.

### Optionally Override `check`

Override `check(self, config=None)` when your channel depends on an external binary or credential file. Return a tuple of `(status, message)` where status is `"ok"`, `"warn"`, or `"error"`. The doctor command displays this output during diagnostics.

```python

# File: agent_reach/channels/myplatform.py

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

"""MyPlatform – example custom channel."""

from urllib.parse import urlparse
from .base import Channel


class MyPlatformChannel(Channel):
    name = "myplatform"
    description = "MyPlatform – custom video & article source"
    backends = ["mytool"]            # external binary that does the heavy lifting

    tier = 1                         # requires a free API key

    def can_handle(self, url: str) -> bool:
        """Accept URLs whose hostname matches myplatform.com."""
        host = urlparse(url).netloc.lower()
        return "myplatform.com" in host

    def check(self, config=None):
        """Verify that the required tool is installed."""
        import shutil
        binary = shutil.which("mytool")
        if binary:
            return "ok", "mytool is available"
        return "warn", (
            "mytool not found. Install with:\n"
            "    pipx install mytool"
        )

```

## Register the Channel

Discovery depends on the global registry inside [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py). Import your new class near the existing channel imports, instantiate it, and append it to `ALL_CHANNELS`. The order of items in the list does not matter.

```python

# File: agent_reach/channels/__init__.py

# Add the import near the top with the other channel imports

from .myplatform import MyPlatformChannel

# Add the instance to the registry list

ALL_CHANNELS.append(MyPlatformChannel())

```

Once registered, the CLI, doctor, and core router automatically recognize the channel without further configuration.

## Verify with the Doctor Command

After saving your files, run the built-in doctor to confirm that Agent Reach detects the new channel and that its dependencies are healthy:

```bash
$ python -m agent_reach.cli doctor
...
✅ myplatform – MyPlatform – custom video & article source (ok)

```

If you authored unit tests for `can_handle` or `check`, execute them with pytest:

```bash
pytest tests/ -v

```

## Reference Implementation

If you need a production example of a concrete channel, examine [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py). It demonstrates the same pattern: mandatory attributes, a hostname check inside `can_handle`, and optional validation logic inside `check`. The core routing logic in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) and the CLI entry point in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) remain untouched because they rely entirely on the `ALL_CHANNELS` registry.

## Summary

- **Subclass `Channel`** from [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) in a new file under `agent_reach/channels/`.
- **Declare `name`, `description`, `backends`, and `tier`** so the CLI can catalog your platform.
- **Implement `can_handle`** to route URLs from your platform to the new channel.
- **Optionally override `check`** to surface dependency diagnostics.
- **Import and append an instance** to `ALL_CHANNELS` in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py).
- **Run `python -m agent_reach.cli doctor`** to verify that the channel is visible and healthy.

## Frequently Asked Questions

### What methods must I implement to add a custom channel for a new platform?

You must implement `can_handle(self, url: str) -> bool`. You should also define the four class attributes `name`, `description`, `backends`, and `tier`. The `check` method is optional but recommended if your channel relies on external binaries or credentials.

### Do I need to modify [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) or [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)?

No. The core router in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) and the CLI in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) discover channels dynamically through the `ALL_CHANNELS` registry in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py). You only need to register your subclass there.

### What is the purpose of the `tier` attribute?

The `tier` attribute signals how much setup the user must perform before the channel works. Use `0` for zero-config platforms, `1` for platforms that need a free API key, and `2` for platforms that require full manual setup or paid credentials.

### How does Agent Reach route a URL to my custom channel?

During processing, [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) iterates over every instance in `ALL_CHANNELS` and calls `can_handle(url)` until one returns `True`. Because your registered subclass is part of that list, the router naturally considers it for any matching URL.