Agent-Reach Channel Base Class Interface: Complete Contract Guide for New Handlers

The Channel base class in agent_reach/channels/base.py mandates four class attributes (name, description, backends, tier) and one abstract method (can_handle) that every platform-specific handler must implement to integrate with the CLI diagnostic system and request router.

Building new platform integrations for Agent-Reach requires adhering to the strict interface contract defined in the abstract base class. Located in agent_reach/channels/base.py, this contract establishes the minimal metadata and behavioral API required for the doctor diagnostic tool and core routing system to recognize, validate, and dispatch requests to your handler without platform-specific hardcoding.

Required Class Attributes

Every subclass must define four class-level fields that declare the channel's identity, dependencies, and configuration complexity.

name and description

The name attribute provides a unique human-readable identifier used in CLI output and configuration files, while description offers a short, user-facing explanation of the platform's functionality. These strings appear in status reports generated by agent_reach/doctor.py and help users understand available integrations.

backends

The backends attribute is a List[str] enumerating external binaries or libraries required to interact with the platform, such as ["yt-dlp"] for YouTube operations. The doctor iterates over this list to verify tool availability during environment health checks, reporting missing dependencies before runtime failures occur.

tier

The tier integer signals configuration complexity: 0 indicates zero-config operation, 1 requires a free API key, and 2 demands user-provided setup or credentials. This classification determines warning severity in diagnostic reports, allowing users to quickly identify which channels require additional configuration before use.

Abstract Method Requirements

can_handle

Subclasses must implement can_handle(self, url: str) -> bool to perform fast URL pattern matching and platform detection. This method returns True when the supplied URL belongs to the platform's domain or matches its URL scheme, enabling agent_reach/core.py to route read and search requests to the correct handler without embedding platform logic in the router. Concrete implementations in agent_reach/channels/youtube.py and agent_reach/channels/twitter.py demonstrate domain-checking patterns using urllib.parse.

Optional Diagnostic Methods

check Method Override

While the base class provides a default check(self, config=None) -> Tuple[str, str] implementation that returns generic backend status, channels requiring complex validation should override this method. The return value must be a tuple of (status, message) where status is either "ok" or "off". Use this hook to verify API token validity, check for specific runtime environments like Node.js, or validate credential files beyond simple binary path existence.

Step-by-Step Implementation Guide

Creating a compliant channel handler involves four concrete steps:

1. Subclass Channel imported from agent_reach/channels/base.py.
2. Declare the four class attributes: name, description, backends, and tier.
3. Implement can_handle with platform-specific URL detection logic that returns a boolean.
4. Optionally override check for custom validation of runtime requirements or credentials.

Minimal Channel Implementation Example

Below is a complete skeleton implementing the contract for a hypothetical "MyPlatform" service. This class can be dropped into agent_reach/channels/ and will immediately integrate with the doctor and CLI systems:

# agent_reach/channels/myplatform.py

from urllib.parse import urlparse
from typing import Tuple

from .base import Channel


class MyPlatformChannel(Channel):
    # Required metadata attributes

    name = "myplatform"
    description = "MyPlatform – example integration"
    backends = ["mytool"]          # External binary dependency

    tier = 0                       # Zero-config (no API keys required)

    # Required: URL routing decision logic

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

    # Optional: Custom health check with specific installation instructions

    def check(self, config=None) -> Tuple[str, str]:
        import shutil
        if not shutil.which("mytool"):
            return "off", "mytool 未安装。安装：pip install mytool"
        return "ok", "mytool 已就绪"

After placing this file in the channels directory, run python -m agent_reach.cli doctor to verify the new channel appears in the diagnostic status table alongside built-in handlers.

Integration with Agent-Reach Subsystems

The strict contract enables seamless integration with two critical components without additional registration code:

Doctor Diagnostic System (agent_reach/doctor.py): This subsystem enumerates all Channel subclasses and invokes check() to produce uniform status reports. The backends and tier attributes drive the diagnostic logic, ensuring users receive actionable warnings about missing dependencies or configuration requirements.

CLI Request Router (agent_reach/core.py): The routing module uses can_handle() to dispatch operations to the correct upstream tool. This decouples routing logic from platform specifics, allowing new channels to handle traffic immediately upon file placement without modifying core system code.

Summary

• The Channel base class in agent_reach/channels/base.py defines four mandatory class attributes: name, description, backends, and tier.
• All subclasses must implement can_handle(url: str) -> bool to enable URL-based request routing by the core system.
• The optional check() method allows custom validation of runtime dependencies, returning a tuple of (status, message) for diagnostic reporting.
• Conforming to this contract automatically integrates your handler with the doctor diagnostic system and CLI router.

Frequently Asked Questions

What happens if I don't implement the can_handle method?

Attempting to instantiate a channel without implementing can_handle raises a TypeError because Channel defines it as an abstract method via Python's abc module. The Agent-Reach CLI will fail to load the channel entirely, preventing it from appearing in diagnostic reports or handling requests.

How does the tier attribute affect channel behavior?

The tier integer does not change runtime execution but controls the severity of diagnostic warnings in agent_reach/doctor.py. Tier 0 channels never emit configuration warnings, tier 1 prompts users to obtain free API keys, and tier 2 indicates that manual setup is required before the channel functions correctly.

Can I specify multiple backends in the backends list?

Yes, the backends attribute accepts a list of strings representing all external dependencies. For example, a complex channel might declare backends = ["ffmpeg", "special-api-client"], and the doctor will verify the presence of each binary during health checks, reporting any missing tools in the status output.

Is the check method required for basic functionality?

No, check is optional. The base class provides a default implementation that returns ("ok", description) based on the backends list. You only need to override it when requiring validation beyond simple binary existence, such as checking API token validity or specific runtime environments.

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