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

To implement a new platform channel in Agent Reach, create a Python class inheriting from Channel in 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.

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 repository.

Understand the Channel Base Class

The Channel abstract base class in 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:

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:

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:

    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:

    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:

    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

Edit agent_reach/channels/init.py to import your class for auto-discovery:

from .myplatform import MyPlatformChannel

Step 6: Verify with CLI Diagnostics

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

python -m agent_reach.cli doctor

Expect output like:

✔ MyPlatform (myplatform) – ok – myplatform-cli

Complete Working Example

Here is the full implementation skeleton for myplatform.py with optional read delegation:

# 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	Abstract Channel class with ordered_backends() and default check()	View on GitHub
agent_reach/channels/twitter.py	Production example implementing multi-backend probing	View on GitHub
agent_reach/channels/__init__.py	Registration point for auto-discovery	View on GitHub
agent_reach/probe.py	probe_command() utility for CLI health checks	View on GitHub
agent_reach/core.py	Router that calls can_handle() to select channels	View on GitHub

Summary

• Inherit from Channel: All platform channels must extend the base class defined in 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 to test backend CLIs and set active_backend to the first healthy option.
• Register explicitly: Import the class in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}