Understanding the Agent Reach Channel Tier System: Tier 0, 1, and 2 Explained

Agent Reach uses a three-tier classification system (Tier 0, 1, and 2) to indicate how much configuration each platform requires, determining whether channels work out-of-the-box, need free credentials, or require optional complex setup before becoming available to agents.

The Agent Reach channel tier system is implemented in the Panniantong/Agent-Reach repository to clearly communicate platform readiness to users. Every supported channel—from YouTube to Twitter—is assigned a tier value that the health checker uses to generate availability reports. Understanding these tiers helps developers know which platforms require immediate setup and which work immediately after installation.

How the Three-Tier Classification Works

The tier system groups platforms based on configuration complexity. Each channel class inherits from a base class that defines the tier attribute, which the CLI doctor command consults when generating status reports.

Tier 0: Zero-Configuration Channels

Tier 0 channels are completely self-contained and require no user action. These platforms use built-in backends that work as soon as you install the package.

Common Tier 0 platforms include:

• youtube – YouTube video and subtitle extraction
• bilibili – Bilibili content access
• github – GitHub repository interactions

In agent_reach/channels/base.py, the base Channel class defines the default tier:

# agent_reach/channels/base.py

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

Tier 1: Free-Key and Login-Required Channels

Tier 1 channels require user-provided credentials—typically a free API key or exported browser cookie—before they become operational. The upstream tool is present in the installation, but the platform cannot authenticate without these credentials.

Typical Tier 1 platforms include:

• twitter – Requires login cookie or API key
• xiaohongshu – Needs exported session cookies
• reddit – Requires API credentials

Until you supply the required authentication, Tier 1 channels show a warn status in health checks and remain unavailable to agents.

Tier 2: Optional Complex Setup Channels

Tier 2 channels represent optional enhancements that may require paid API tokens, multi-backend choices, or additional infrastructure. While these channels can function without extra setup, they unlock full capabilities only after complex configuration.

Examples include:

• exa_search – Exa search API (optional paid token for full features)
• v2ex – Optional backend configurations

Like Tier 1, these channels are optional and display as unavailable until configured, but they never block core functionality.

Impact on Platform Availability and Health Checks

The agent_reach/doctor.py module implements the health-check logic that translates tier values into user-facing availability status. When you run the diagnostic command, the system iterates through all channels and groups them by tier in the output report.

In agent_reach/doctor.py (lines 62-86), the formatting logic categorizes channels as follows:

# agent_reach/doctor.py – formatting logic

# Tier 0 — zero config

# Tier 1 — needs free key / login

# Tier 2 — optional complex setup

The health check uses per-channel exception handling, meaning a misconfigured Tier 1 or Tier 2 channel never crashes the entire system. Instead, the report clearly distinguishes between:

• Immediately available (✅ 装好即用): All Tier 0 channels
• Installed but requiring action (可选渠道（已安装）): Tier 1 and Tier 2 channels that need configuration

Checking Channel Tiers Programmatically

You can inspect tier values and health status through both the CLI and Python API.

Running the Health Check from CLI

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

$ python -m agent_reach.cli doctor

Sample output shows the tier-based grouping:

✅ 装好即用：
  ✅ YouTube 视频和字幕
可选渠道（已安装）：
  ✅ Twitter

Accessing Tier Information in Python

Retrieve tier data for all registered channels programmatically:

from agent_reach.channels import get_all_channels

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

This produces output like:

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

Verifying Individual Channel Health

Check a specific channel's readiness by passing your configuration object:

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", "需要登录"

Summary

• Tier 0 channels in agent_reach/channels/base.py require zero configuration and work immediately after installation.
• Tier 1 channels need free credentials (cookies or API keys) and show as unavailable until configured.
• Tier 2 channels offer optional enhanced functionality requiring complex setup or paid tokens.
• The agent_reach/doctor.py health checker tolerates failures in Tier 1 and Tier 2 channels, ensuring one misconfigured platform never breaks the entire system.
• Use python -m agent_reach.cli doctor to view your current tier status and identify which channels need activation.

Frequently Asked Questions

What is the difference between Tier 1 and Tier 2 channels in Agent Reach?

Tier 1 channels require free authentication credentials like browser cookies or API keys that cost nothing but must be manually exported and configured. Tier 2 channels involve optional complex setup, often including paid API tokens or multi-backend infrastructure choices that enhance functionality beyond the basic implementation. Both tiers appear as unavailable in health checks until you complete their respective configuration steps.

How do I make a Tier 1 channel available in Agent Reach?

Export the required credentials from your browser or API provider and place them in the configuration file at ~/.agent-reach/config.yaml. For cookie-based authentication, follow the Cookie Export guide in the repository documentation to extract the necessary session data. Once configured, rerun python -m agent_reach.cli doctor to verify the channel status changes from warn to available.

Will unavailable Tier 1 or Tier 2 channels break my Agent Reach installation?

No. The health checker in agent_reach/doctor.py implements per-channel exception handling with try/except blocks during the check_all process. A misconfigured Tier 1 or Tier 2 channel simply displays as unavailable in the report without affecting Tier 0 channels or overall system functionality.

Where can I find which tier a specific platform belongs to?

Check the source code in agent_reach/channels/base.py for the base class definition, or examine the specific channel implementation file in the agent_reach/channels/ directory (such as twitter.py or youtube.py). Each channel class explicitly sets its tier attribute to 0, 1, or 2, which you can also inspect programmatically using get_all_channels() as shown in the examples above.

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