Understanding Agent-Reach Platform Tiers: Zero-Config, Free-Key, and Full-Setup Explained

Agent-Reach organizes every supported platform into three configuration tiers—zero-config (tier 0), free-key (tier 1), and full-setup (tier 2)—that determine whether a channel works immediately, requires a developer API key, or needs a complete OAuth flow.

Agent-Reach is an open-source Python framework that unifies access to web platforms through a standardized channel interface. The Agent-Reach platform tiers system classifies each integration by its setup complexity, allowing developers to instantly identify which channels work out-of-the-box and which require credentials. This tiering mechanism is enforced in the core BaseChannel class and exposed through the CLI's diagnostic tools.

The Three Agent-Reach Platform Tiers

Each channel class in agent_reach/channels/*.py declares a tier attribute that inherits from the base definition in agent_reach/channels/base.py at line 35:

tier: int = 0  # 0=zero-config, 1=needs free key, 2=needs setup

Tier 0 – Zero-Config

Zero-config channels operate immediately after installation with no API keys, tokens, or authentication flows. These platforms expose public data or use scraping methods that require no user credentials.

Current tier 0 implementations include:

• YouTube (agent_reach/channels/youtube.py, line 27)
• Web (agent_reach/channels/web.py, line 14)
• V2EX (agent_reach/channels/v2ex.py, line 24)
• RSS (agent_reach/channels/rss.py, line 11)
• GitHub (agent_reach/channels/github.py, line 13)
• Exa Search (agent_reach/channels/exa_search.py, line 16)

Tier 1 – Free-Key

Free-key platforms require a free developer API key that you obtain from the service's portal and supply via environment variables or ~/.agent-reach/config.yaml. These channels offer richer data access than tier 0 while maintaining simple setup.

Tier 1 channels include:

• Xueqiu (agent_reach/channels/xueqiu.py, line 153)
• XiaoYuzhou (agent_reach/channels/xiaoyuzhou.py, line 14)
• XiaoHongShu (agent_reach/channels/xiaohongshu.py, line 153)
• Twitter (agent_reach/channels/twitter.py, line 12)
• Bilibili (agent_reach/channels/bilibili.py, line 39)
• OpenCLI site (agent_reach/channels/_opencli_site.py, line 22)

A special case is Reddit (agent_reach/channels/reddit.py, line 39), which technically requires a free key but also demands manual verification steps beyond standard tier 1 requirements.

Tier 2 – Full-Setup

Full-setup channels require complete OAuth workflows or complex credential configurations, including user login and app registration. Currently, LinkedIn (agent_reach/channels/linkedin.py, line 16) is the primary tier 2 implementation, requiring the OAuth flow documented in agent_reach/guides/setup-linkedin.md.

How Platform Tiers Work in the Codebase

The tier system influences three core framework behaviors:

1. Channel Discovery – When processing a URL, Agent-Reach iterates through all channel classes and selects the first match based on the can_handle method. Lower-tier channels receive priority, ensuring friction-free experiences when multiple handlers exist.

2. Doctor Diagnostics – The doctor command in agent_reach/doctor.py (lines 66-90) groups output by tier, displaying zero-config channels first, then free-key channels, and finally full-setup channels. This lets you instantly see which platforms are ready to use.

3. Configuration Validation – The framework checks the tier attribute to determine which validation logic applies. Tier 0 channels skip credential checks entirely, while tier 1 and 2 channels verify the presence of required keys or tokens.

Practical Examples by Tier

Using a Zero-Config Channel (YouTube)

Since YouTube operates at tier 0, no API key is required:

from agent_reach import Core

core = Core()
video_info = core.read("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print(video_info.title)  # Output: Rick Astley - Never Gonna Give You Up

Configuring a Free-Key Channel (Twitter)

First, export your free bearer token:

export TWITTER_BEARER_TOKEN="YOUR_FREE_BEARER"

Then use the channel:

from agent_reach import Core

core = Core()
tweets = core.search("lang:en openai")
for t in tweets[:5]:
    print(t.text)

Without the environment variable or entry in ~/.agent-reach/config.yaml, the channel reports "missing-key" status in the doctor output.

Setting Up a Full-Setup Channel (LinkedIn)

For tier 2 platforms, use the installation helper:

python -m agent_reach.cli install --platform linkedin

This launches the OAuth flow described in the platform-specific guide. Upon completion, the token is saved to your configuration, and the channel status moves from "needs-setup" to "ok".

Checking Platform Status

Use the CLI to view all channels grouped by tier:

python -m agent_reach.cli doctor --list

Typical output shows:

• 🟢 Tier 0: YouTube, Web, RSS (status=ok)
• 🟢 Tier 1: Twitter (status=missing-key if not configured)
• 🔴 Tier 2: LinkedIn (status=needs-setup until OAuth completes)

Summary

• Agent-Reach platform tiers classify integrations into three levels: zero-config (0), free-key (1), and full-setup (2).
• The tier attribute is defined in agent_reach/channels/base.py at line 35 and implemented in each channel class.
• Tier 0 includes YouTube, Web, RSS, GitHub, and Exa Search, requiring no authentication.
• Tier 1 covers Twitter, Bilibili, and Chinese social platforms like XiaoHongShu, requiring free API keys.
• Tier 2 currently includes LinkedIn, requiring full OAuth workflows.
• The doctor command uses tiers to prioritize diagnostics, displaying zero-config channels first.

Frequently Asked Questions

What is the difference between tier 0 and tier 1 in Agent-Reach?

Tier 0 channels work immediately after installation with no configuration, while tier 1 channels require you to obtain a free API key from the platform's developer portal and add it to your environment variables or config.yaml. Tier 0 uses public endpoints or scraping, whereas tier 1 accesses authenticated APIs.

How do I check which tier a specific platform uses?

Run python -m agent_reach.cli doctor --list to see all channels grouped by tier. Alternatively, inspect the source file for that platform in agent_reach/channels/ and check the tier class attribute, defined at the module level (e.g., line 27 in youtube.py).

Can I use a tier 2 platform like LinkedIn without completing the full OAuth setup?

No. Tier 2 platforms require the complete OAuth flow documented in their respective setup guides. The framework will report "needs-setup" status and refuse to process requests until you run python -m agent_reach.cli install --platform linkedin and complete the authentication.

Why does Reddit show as tier 1 but require additional verification?

Reddit is a special case classified as tier 1 because it technically only requires a free developer key. However, as implemented in agent_reach/channels/reddit.py at line 39, it demands manual verification steps beyond standard key entry, making it behave more like a hybrid between tier 1 and tier 2.

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