Fallback Order for Xiaohongshu Backends in Agent Reach: Priority and Configuration

Agent Reach probes Xiaohongshu backends in the fixed sequence OpenCLI → xiaohongshu-mcp → xhs-cli, automatically falling back to the next available option when the preferred backend is unreachable.

Agent Reach abstracts social media platforms as channels that support multiple backend implementations. For the Xiaohongshu (小红书) channel, the fallback order for Xiaohongshu backends in Agent Reach is defined in the source code to ensure resilient automation across different runtime environments.

How the Fallback Order Is Defined

The fallback mechanism relies on a declared list of backends and a base class method that determines probing priority.

Backend Declaration in xiaohongshu.py

In agent_reach/channels/xiaohongshu.py, the XiaoHongShuChannel class declares its supported backends as a class attribute:

class XiaoHongShuChannel(Channel):
    …
    backends = ["OpenCLI", "xiaohongshu-mcp", "xhs-cli (xiaohongshu-cli)"]

This ordered list establishes the default fallback hierarchy.

The ordered_backends() Method

The Channel base class in agent_reach/channels/base.py implements ordered_backends(), which returns the probing sequence. By default, it returns the backends list exactly as declared, but it can also prioritize a user-specified override.

The Three-Tier Fallback Sequence

When Agent Reach initializes a Xiaohongshu connection, it probes backends in this order:

1. OpenCLI – The preferred desktop environment backend that reuses existing Chrome sessions.
2. xiaohongshu-mcp – A headless-browser service designed for server-side automation.
3. xhs-cli (xiaohongshu-cli) – The legacy upstream CLI tool retained as a final fallback.

If agent_reach/probe.py determines that a backend is unavailable (e.g., Chrome is not running for OpenCLI), Agent Reach automatically proceeds to the next backend in the sequence.

Configuring Backend Priority

Users can override the default fallback order by providing a configuration dictionary. When the key xiaohongshu_backend is present, ordered_backends() moves that specific backend to the front of the queue.

from agent_reach.channels.xiaohongshu import XiaoHongShuChannel

# Default probing order

xhs = XiaoHongShuChannel()
print(xhs.ordered_backends())

# → ['OpenCLI', 'xiaohongshu-mcp', 'xhs-cli (xiaohongshu-cli)']

# Force the MCP backend to be tried first

config = {"xiaohongshu_backend": "xiaohongshu-mcp"}
print(xhs.ordered_backends(config))

# → ['xiaohongshu-mcp', 'OpenCLI', 'xhs-cli (xiaohongshu-cli)']

This configuration pattern allows environment-specific optimization without modifying the core channel definition.

Summary

• OpenCLI takes precedence as the default backend for desktop environments.
• The fallback order is defined in agent_reach/channels/xiaohongshu.py and processed by ordered_backends() in the base channel class.
• Agent Reach automatically skips unavailable backends and proceeds to the next option in the sequence.
• Users can override the priority via the xiaohongshu_backend configuration key.
• The contract is verified by tests/test_channel_contracts.py, ensuring ordered_backends() always returns a valid permutation of the declared backends.

Frequently Asked Questions

What happens if all Xiaohongshu backends are unavailable?

If none of the three backends respond to the probe check, Agent Reach raises a BackendUnavailableError after exhausting the sequence. The error message indicates which backends were attempted and why each failed (e.g., missing Chrome binary, network timeout, or authentication failure).

Can I disable specific backends from the fallback order?

Currently, the backends list in XiaoHongShuChannel is static. To exclude a backend, you must subclass the channel or provide a configuration that forces a specific working backend to the front. The ordered_backends() method guarantees the requested backend is tried first, effectively bypassing others if it succeeds.

Where does the backend probing logic reside?

The lightweight availability checks are implemented in agent_reach/probe.py, which is invoked by the channel's check() method. This module performs environment detection (e.g., verifying Chrome processes for OpenCLI or HTTP health checks for xiaohongshu-mcp) without fully initializing the backend.

Is the fallback order the same across all Agent Reach versions?

As of the current implementation in the Panniantong/Agent-Reach repository, the fallback order for Xiaohongshu backends is hardcoded in the class definition. Future versions may expose this ordering through configuration files, but the current release requires code modification to change the base sequence.

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