How to Add a New Channel to Agent Reach: A Complete Implementation Guide

To add a new channel to Agent Reach, create a Python class inheriting from Channel in agent_reach/channels/base.py, implement the can_handle() and check() methods, and register an instance in the ALL_CHANNELS list inside agent_reach/channels/__init__.py.

Agent Reach is an extensible Python framework that treats every supported platform as a channel. Adding a new channel to Agent Reach requires implementing a concrete class that satisfies the contract defined by the abstract Channel base class and registering it in the global channel registry. This guide walks through the exact implementation steps using the actual source code structure from the Panniantong/Agent-Reach repository.

Understanding the Channel Architecture

Every channel in Agent Reach inherits from the abstract base class Channel defined in agent_reach/channels/base.py. This base class establishes a strict contract that every concrete implementation must satisfy to integrate with the framework's health-checking and routing systems.

The two required methods define platform detection and backend validation:

• can_handle(url: str) -> bool – Determines if a given URL belongs to this channel's platform by parsing the netloc or path patterns.
• check(config=None) -> Tuple[str, str] – Probes required external executables, sets self.active_backend, and returns a status tuple. The first element must be one of ok, warn, off, or error, while the second provides a human-readable message.

For probing external tools, implementations should use probe_command() from agent_reach/probe.py, which handles executable discovery and version checking consistently across platforms.

Step-by-Step Implementation Guide

Step 1: Create the Channel Implementation File

Create a new Python file under agent_reach/channels/ with your channel name. Import the Channel base class and define your concrete implementation with appropriate metadata attributes:

# agent_reach/channels/example.py

from .base import Channel

class ExampleChannel(Channel):
    name = "example"
    description = "Example platform description"
    backends = ["example-cli"]
    tier = 0

Step 2: Implement the Required Methods

Implement can_handle() to identify URLs belonging to your platform using urlparse, and implement check() to validate the backend tool is installed and functional:

    def can_handle(self, url: str) -> bool:
        from urllib.parse import urlparse
        return "example.com" in urlparse(url).netloc

    def check(self, config=None):
        from agent_reach.probe import probe_command
        probe = probe_command("example-cli", ["--version"], package="example-cli")
        
        if probe.status == "missing":
            self.active_backend = None
            return "off", "example-cli not installed. Install with `pip install example-cli`"
        
        if not probe.ok:
            self.active_backend = None
            return "error", f"example-cli cannot run: {probe.hint or probe.output}"
        
        self.active_backend = "example-cli"
        return "ok", "example-cli is ready"

Optional attributes like usage can be added to provide CLI invocation hints that appear in the doctor output, following the pattern seen in agent_reach/channels/instagram.py.

Step 3: Register the Channel in the Registry

Edit agent_reach/channels/__init__.py to import your new class and append an instance to the ALL_CHANNELS list:

from .example import ExampleChannel

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

    ExampleChannel(),
]

The registry automatically discovers all channels in this list during the health-check routine.

Complete Working Example

Here is a full, minimal implementation for a hypothetical platform saved as agent_reach/channels/example.py:

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

"""Example – a minimal channel implementation."""
from .base import Channel

class ExampleChannel(Channel):
    name = "example"
    description = "Demo platform supporting video extraction"
    backends = ["example-cli"]
    tier = 0

    def can_handle(self, url: str) -> bool:
        from urllib.parse import urlparse
        return "example.com" in urlparse(url).netloc

    def check(self, config=None):
        from agent_reach.probe import probe_command
        probe = probe_command("example-cli", ["--version"], package="example-cli")
        
        if probe.status == "missing":
            self.active_backend = None
            return "off", "example-cli missing – install via pip."
        
        if not probe.ok:
            self.active_backend = None
            return "error", f"example-cli broken: {probe.hint or probe.output}"
        
        self.active_backend = "example-cli"
        return "ok", "example-cli ready"

Verify Your Implementation

After saving your channel file and updating the registry, run the doctor command to verify the integration:

python -m agent_reach.cli doctor

You should see output similar to:

example – ok – example-cli ready

If the status shows off or error, the message will indicate whether the executable is missing or malfunctioning, allowing you to debug the check() implementation.

Summary

• Inherit from Channel – All channels must subclass the abstract base class in agent_reach/channels/base.py and implement the required interface.
• Implement can_handle() – This method enables URL routing by returning True when the URL belongs to your platform.
• Implement check() – Use probe_command() from agent_reach/probe.py to validate external tools and return status tuples (ok, warn, off, error).
• Register in ALL_CHANNELS – Import and instantiate your class in agent_reach/channels/__init__.py to make it discoverable.
• Verify with doctor – Run python -m agent_reach.cli doctor to confirm the channel is active and the backend is properly detected.

Frequently Asked Questions

What methods must I implement when adding a new channel to Agent Reach?

You must implement can_handle(url: str) and check(config=None). The can_handle method enables the router to identify platform-specific URLs, while check validates that required backend executables are installed and functional, setting self.active_backend when successful.

How does Agent Reach detect if a backend tool is installed?

Agent Reach uses the probe_command() function from agent_reach/probe.py to check for executable availability. This utility runs version checks and returns a status object indicating whether the tool is missing, broken, or ready, allowing your check() method to return appropriate status messages.

Can I add optional functionality like transcribe methods to my channel?

Yes, you can extend your channel class with additional methods such as transcribe() for platforms that support audio processing. While can_handle and check are required for registration, optional methods enable platform-specific features that agents can invoke when the backend supports them.

Where does Agent Reach look for channel registrations?

Agent Reach discovers channels through the ALL_CHANNELS list defined in agent_reach/channels/__init__.py. The health-check routine iterates over this list to run diagnostics, so your new channel must be imported and instantiated there to be recognized by the system.

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