Understanding Agent Reach's Channel Tier System: How Tiers 0, 1, and 2 Control Platform Availability

The channel tier system in Agent Reach categorizes every supported platform into one of three tiers (0, 1, or 2) based on configuration requirements, directly determining which platforms are immediately usable and which require additional credentials or setup.

Agent Reach implements a sophisticated availability model that groups platforms like YouTube, Twitter, and Reddit into distinct configuration tiers. This system, defined in the core channel architecture, enables the CLI health checker to generate accurate status reports and helps users understand exactly what steps are needed to unlock specific platform integrations.

How the Channel Tier System Works

The tier system is defined in the base channel class at agent_reach/channels/base.py, where each Channel instance exposes a tier attribute that specifies its configuration requirements:

# agent_reach/channels/base.py

class Channel(ABC):
    ...
    tier: int = 0                     # 0=zero-config, 1=needs free key, 2=needs setup

Channels inherit from this base class and set their specific tier value according to the complexity of their setup process. The doctor.py module (lines 62–86) consumes these values to generate human-readable health reports that group platforms by their readiness state.

Tier 0: Zero-Configuration Platforms

Tier 0 channels require no user intervention and work immediately after installation. These platforms use built-in backends that do not require API keys, cookies, or external credentials.

Common Tier 0 platforms include:

• YouTube – video and subtitle extraction works out-of-the-box
• Bilibili – built-in backend support
• GitHub – standard API access without additional configuration

These channels always report as available and never block the overall health status of your Agent Reach installation.

Tier 1: Free-Key or Login Required

Tier 1 channels require user-provided credentials—typically a free API key or exported browser cookie—before they become operational. While the underlying tool is present and installed, the channel remains in a warn state until proper authentication is configured.

Examples of Tier 1 platforms include:

• Twitter/X – requires exported cookies or login credentials
• Reddit – needs API key configuration
• Xiaohongshu – requires cookie export from browser session

Until you supply the required credentials (see the project's Cookie Export guide), these channels appear as "installed but unavailable" in health reports.

Tier 2: Optional Complex Setup

Tier 2 channels represent optional enhancements that function without additional setup but can be improved with paid APIs or multi-backend configurations. These are considered premium or extended integrations.

Notable Tier 2 examples include:

• Exa Search – works without tokens but supports paid API for enhanced results
• V2EX – optional backend configurations available

These channels do not affect core functionality and remain optional even when properly configured.

Impact on Platform Availability

The tier system directly controls how platforms appear in the health-check report generated by python -m agent_reach.cli doctor. The implementation in agent_reach/doctor.py uses a try/except pattern in the check_all function, ensuring that misconfigured Tier 1 or Tier 2 channels never crash the entire system—they simply report as unavailable.

Availability behavior by tier:

• Tier 0: Immediately marked as ✅ 装好即用 (ready to use) and fully operational for agents
• Tier 1: Listed under 可选渠道（已安装） (optional channels installed) with warn status until credentials are provided; agents cannot use these channels until configured
• Tier 2: Also listed as optional with warn status when enhanced features are missing; basic functionality may work depending on the specific implementation

This granular approach allows Agent Reach to ship with broad platform support while clearly communicating which integrations require additional user action.

Checking Channel Tiers and Health Status

Running the Health Check from CLI

Execute the built-in doctor command to see your current platform availability:

$ python -m agent_reach.cli doctor

The output organizes channels by tier, showing immediate availability for Tier 0 and configuration prompts for Tier 1 and 2:

✅ 装好即用：
  ✅ YouTube 视频和字幕
可选渠道（已安装）：
  ⚠️ Twitter (需要登录)

Accessing Tier Information Programmatically

Inspect channel tiers directly in Python to build custom availability dashboards:

from agent_reach.channels import get_all_channels

for ch in get_all_channels():
    print(f"{ch.name:12} → tier {ch.tier}  ({ch.description})")

Typical output shows the tier distribution:

youtube      → tier 0  (YouTube 视频和字幕)
twitter      → tier 1  (Twitter/X 社交平台)
exa_search   → tier 2  (Exa 搜索 API)

Checking Individual Channel Health

Validate specific channel configurations before running agents:

from agent_reach.config import Config
from agent_reach.channels import twitter

cfg = Config()                 # loads ~/.agent-reach/config.yaml

status, message = twitter.check(cfg)
print(status, message)        # e.g. "warn", "需要登录"

This programmatic access allows you to gate agent workflows based on actual platform availability rather than assuming all channels are operational.

Summary

• Channel tiers are defined in agent_reach/channels/base.py via the tier attribute (0, 1, or 2) and determine configuration requirements for each platform.
• Tier 0 platforms (YouTube, Bilibili, GitHub) require zero configuration and are immediately available.
• Tier 1 platforms (Twitter, Reddit, Xiaohongshu) need free API keys or exported cookies and show warn status until configured.
• Tier 2 platforms offer optional enhancements with complex setup; they do not block core functionality.
• The health checker (doctor.py) groups channels by tier and tolerates failures, ensuring misconfigured optional channels never break the system.

Frequently Asked Questions

What is the difference between Tier 1 and Tier 2 channels?

Tier 1 channels require mandatory credentials (free API keys or cookies) to function at all, while Tier 2 channels work without additional setup but support enhanced features through optional paid services or complex configurations. Tier 1 channels block agent usage for that platform until configured, whereas Tier 2 channels may provide basic functionality without the enhanced setup.

How do I make a Tier 1 channel available for use?

You must export the required credentials from your browser or generate a free API key from the platform provider, then place them in the Agent Reach configuration file (typically ~/.agent-reach/config.yaml). Refer to the project's docs/cookie-export.md for specific export instructions for platforms like Twitter and Reddit.

Does a misconfigured Tier 2 channel break my Agent Reach installation?

No, the health checker in agent_reach/doctor.py uses isolated try/except blocks when validating channels, meaning a failure or missing configuration for any Tier 1 or Tier 2 channel only affects that specific platform's availability status. The system continues to operate normally using Tier 0 channels and any properly configured Tier 1 or Tier 2 channels.

Where is the channel tier defined in the Agent Reach source code?

The tier is defined as a class attribute in agent_reach/channels/base.py at line 35, where the base Channel class declares tier: int = 0. Individual channel implementations in agent_reach/channels/*.py override this default value to specify their specific configuration requirements (0, 1, or 2).

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