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

> Learn how to implement a new platform channel in Agent Reach. This guide details creating Python classes, defining metadata, implementing routing and health checks, and registering your new channel.

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

---

**To implement a new platform channel in Agent Reach, create a Python class inheriting from `Channel` in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), define metadata fields (`name`, `description`, `backends`, `tier`), implement `can_handle()` for URL routing and `check()` for backend health verification, then register the class in [`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 located in the `agent_reach/channels/` package. When you implement a new platform channel in Agent Reach's channels directory, you extend the abstract `Channel` base class to integrate with the framework's auto-discovery and diagnostic systems according to the patterns established in the [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) repository.

## Understand the Channel Base Class

The [Channel](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) 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 between Agent Reach and platform-specific implementations. Every channel must implement these core properties:

- **`name`**: Short identifier used in CLI arguments and configuration keys (e.g., `"twitter"`, `"youtube"`)
- **`description`**: Human-readable summary displayed by diagnostics
- **`backends`**: Ordered list of command-line tools that can fulfill requests (e.g., `["twitter-cli", "OpenCLI"]`)
- **`tier`**: Integer indicating setup complexity (`0` = zero-config, `1` = needs API key, `2` = full user setup)
- **`active_backend`**: Set by `check()` to the first healthy backend from the `backends` list

The base class provides `ordered_backends(config)` to respect user overrides via configuration or environment variables, and a default `check()` that real channels override to probe their backends.

## Step-by-Step Implementation Guide

### Step 1: Scaffold the Channel Module

Create a new file at `agent_reach/channels/<platform>.py`. For a platform called MyPlatform, the file structure looks like:

```text
agent_reach/
└─ channels/
   ├─ base.py
   ├─ twitter.py
   └─ myplatform.py      # New file

```

### Step 2: Define Channel Metadata

Import the base class and declare your subclass with required metadata:

```python
from .base import Channel
from agent_reach.probe import probe_command

class MyPlatformChannel(Channel):
    name = "myplatform"                     # CLI and config identifier

    description = "MyPlatform – short description"
    backends = ["myplatform-cli", "OpenCLI"]  # Fallback order matters

    tier = 1                                 # 1 = requires API key setup

```

### Step 3: Implement URL Detection with `can_handle()`

The `can_handle()` method receives a URL string and returns `True` if this channel should handle it. Parse the hostname to match your platform's domains:

```python
    def can_handle(self, url: str) -> bool:
        from urllib.parse import urlparse

        domain = urlparse(url).netloc.lower()
        return "myplatform.com" in domain or "mp.com" in domain

```

### Step 4: Add Backend Health Checks with `check()`

Implement `check()` to probe each backend and select the first usable one. This follows the pattern from [agent_reach/channels/twitter.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py):

```python
    def check(self, config=None):
        """Probe each backend; first healthy one becomes active."""
        self.active_backend = None
        findings = []

        for backend in self.ordered_backends(config):
            if backend == "myplatform-cli":
                result = self._check_myplatform_cli()
            elif backend == "OpenCLI":
                result = self._check_opencli()
            else:
                continue

            if result is None:
                continue
            findings.append((backend, *result))

        # Prefer "ok", then "warn"

        for wanted in ("ok", "warn"):
            for backend, status, message in findings:
                if status == wanted:
                    self.active_backend = backend
                    return status, message

        if findings:
            return "error", "\n".join(msg for _, _, msg in findings)

        return "warn", (
            "MyPlatform CLI not installed. Install with:\n"
            "  pipx install myplatform-cli"
        )

```

Helper methods probe specific CLIs using `probe_command` from [agent_reach/probe.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py):

```python
    def _check_myplatform_cli(self):
        probe = probe_command(
            "myplatform",
            ["status"],
            timeout=15,
            retries=1,
            package="myplatform-cli"
        )
        if probe.status == "missing":
            return None
        if probe.status == "broken":
            return "error", f"CLI broken.\n{probe.hint}"
        if probe.ok and "ready" in probe.output.lower():
            return "ok", "myplatform-cli ready"
        return "warn", "CLI installed but not authenticated"

```

### Step 5: Register in [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py)

Edit [agent_reach/channels/__init__.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) to import your class for auto-discovery:

```python
from .myplatform import MyPlatformChannel

```

### Step 6: Verify with CLI Diagnostics

Run the built-in diagnostics to verify discovery and health:

```bash
python -m agent_reach.cli doctor

```

Expect output like:

```text
✔ MyPlatform (myplatform) – ok – myplatform-cli

```

## Complete Working Example

Here is the full implementation skeleton for [`myplatform.py`](https://github.com/Panniantong/Agent-Reach/blob/main/myplatform.py) with optional read delegation:

```python

# agent_reach/channels/myplatform.py

from .base import Channel
from agent_reach.probe import probe_command
from urllib.parse import urlparse


class MyPlatformChannel(Channel):
    name = "myplatform"
    description = "MyPlatform integration"
    backends = ["myplatform-cli", "OpenCLI"]
    tier = 1

    def can_handle(self, url: str) -> bool:
        domain = urlparse(url).netloc.lower()
        return "myplatform.com" in domain

    def check(self, config=None):
        self.active_backend = None
        findings = []

        for backend in self.ordered_backends(config):
            if backend == "myplatform-cli":
                result = self._probe_cli()
            elif backend == "OpenCLI":
                result = self._check_opencli()
            else:
                continue

            if result:
                findings.append((backend, *result))

        for wanted in ("ok", "warn"):
            for backend, status, msg in findings:
                if status == wanted:
                    self.active_backend = backend
                    return status, msg

        return "warn", "No backend available"

    def _probe_cli(self):
        p = probe_command(
            "myplatform", 
            ["status"], 
            timeout=10, 
            package="myplatform-cli"
        )
        if p.status == "missing":
            return None
        if p.status == "ok":
            return "ok", "Ready"
        return "warn", p.hint

    def read(self, url: str):
        """Delegate reading to the active backend."""
        if self.active_backend == "myplatform-cli":
            return probe_command("myplatform", ["read", url]).output
        raise RuntimeError("No active backend for read")

```

## Key Files Reference

| File | Purpose | Source |
|------|---------|--------|
| [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) | Abstract `Channel` class with `ordered_backends()` and default `check()` | [View on GitHub](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) |
| [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) | Production example implementing multi-backend probing | [View on GitHub](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) |
| [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) | Registration point for auto-discovery | [View on GitHub](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) |
| [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) | `probe_command()` utility for CLI health checks | [View on GitHub](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) |
| [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) | Router that calls `can_handle()` to select channels | [View on GitHub](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) |

## Summary

- **Inherit from `Channel`**: All platform channels must extend the base class defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) and implement required metadata properties.
- **Implement `can_handle()`**: This method determines URL routing by inspecting domains or path patterns.
- **Probe with `check()`**: Use `probe_command()` from [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) to test backend CLIs and set `active_backend` to the first healthy option.
- **Register explicitly**: Import the class in [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) for the auto-discovery mechanism to find it.
- **Verify with diagnostics**: Run `python -m agent_reach.cli doctor` to confirm the channel appears with correct status.

## Frequently Asked Questions

### What is the Channel base class in Agent Reach?

The `Channel` base class is an abstract interface defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py) that standardizes how Agent Reach interacts with platform-specific code. It provides helper methods like `ordered_backends()` and enforces the implementation of `can_handle()` and `check()` in subclasses.

### How do I test if my new channel is working correctly?

Run `python -m agent_reach.cli doctor` to execute the diagnostic suite. This command discovers all registered channels, runs their `check()` methods, and reports backend health. You should see your channel listed with either "ok", "warn", or "error" status.

### Can I support multiple backends for a single platform?

Yes. Set the `backends` class property to an ordered list of CLI names (e.g., `["myplatform-cli", "OpenCLI"]`). In your `check()` method, probe each backend and return the first one with "ok" status. The `ordered_backends()` helper respects user configuration overrides via the `<channel>_backend` config key or corresponding environment variables.

### How do I handle platform-specific API authentication?

Use the `tier` property to signal authentication requirements (`1` for API key, `2` for OAuth). In `check()`, probe for valid credentials by running a lightweight command (like `status` or `whoami`) and return `"warn"` if the CLI is installed but unauthenticated, with a message directing users to setup steps.