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

> Understand the Agent Reach channel tier system (Tier 0, 1, 2). Learn how platform configuration determines channel availability for agents, from out-of-the-box to complex setup.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: deep-dive
- Published: 2026-06-27

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), the base `Channel` class defines the default tier:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) (lines 62-86), the formatting logic categorizes channels as follows:

```python

# 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:

```bash
$ 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:

```python
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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/twitter.py) or [`youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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.