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

> Understand the Channel base class contract in Agent-Reach. Learn the required attributes and the can_handle method for integrating new handlers with the CLI diagnostic system.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: api-reference
- Published: 2026-06-08

---

**The `Channel` base class in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) and [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.