How the Agent Reach Format Command Cleans Xiaohongshu API JSON Output

The format_xhs_result function in Agent Reach compresses raw Xiaohongshu API payloads by up to 80% through input detection, field normalization, and selective extraction of LLM-relevant data.

Agent Reach is an open-source framework that standardizes interactions with social media APIs for downstream AI processing. When working with the Xiaohongshu (XHS) API, the raw JSON responses contain extensive metadata—avatars, tracking tokens, and nested structures—that consume unnecessary tokens when passed to language models. The format_xhs_result command, implemented in the XiaoHongShu channel, solves this by stripping redundant fields while preserving critical content, engagement metrics, and media references.

Input Type Detection and Container Extraction

The cleaning process begins with intelligent input classification in agent_reach/channels/xiaohongshu.py (lines 40–59).

The function first determines the structure of the incoming payload:

• List input: Each element is processed individually via [_clean_note(item) for item in data]
• Dictionary with container keys: The function searches for standard wrapper keys such as "items" or "data" (commonly used by search_feeds endpoints) and extracts the inner list for batch processing
• Single note dictionary: Treated as a standalone document and passed directly to _clean_note
• Primitives: Strings, integers, or None values are returned unchanged to prevent exceptions

This routing logic ensures that whether you pass a single note, a search result page, or an already-cleaned object, the formatter handles it appropriately without raising type errors.

Note-Level Field Normalization

Once the input is classified, individual notes are passed to _clean_note (lines 62–130), which performs surgical extraction of only the fields needed for LLM consumption.

Core Identifiers and Content Fallback

The formatter preserves essential identity fields: id, note_id, xsec_token, title, desc, type, and time are copied verbatim when present.

For content handling, the function implements a fallback strategy: if the API returns content but omits desc, the content value is retained under the "content" key. This ensures text data is never lost regardless of which XHS endpoint generated the payload.

Author Metadata Extraction

Author information is normalized by merging fields from either user or author dictionaries into a minimal user object containing only nickname, user_id, and nick_name. Extraneous profile data like avatars, bios, and verification badges are deliberately discarded to reduce token count.

Engagement Metrics Deduplication

The formatter resolves engagement data from multiple possible locations within the XHS schema. It checks interact_info, note_interact_info, and top-level keys to extract liked_count, collected_count, comment_count, and share_count. This deduplication ensures consistent access patterns regardless of which API version returned the data.

Image and Tag Simplification

Media references are flattened to raw URLs only. The function traverses image_list or images_list arrays, extracting values from url, url_default, or original fields while discarding dimensions, moderation flags, and processing metadata.

Tags undergo similar flattening: the function handles both dictionary-based tags ({"name": "旅行"}) and plain strings, returning a simple list of tag names.

Comment Streamlining

When comments arrays are present, each comment is processed by _clean_comment (lines 132–146). This helper retains only the content, a simplified user string (nickname only), and engagement counters (like_count, sub_comment_count). Nested reply trees and user avatars are removed.

Graceful Pass-Through for Invalid Inputs

The formatter implements defensive programming for edge cases. Empty dictionaries, empty lists, unexpected strings, or None values bypass the cleaning pipeline and return unchanged. This prevents runtime crashes when the XHS API returns malformed responses or rate-limit messages, allowing upstream error handling to manage those cases separately.

Implementation Examples

The following examples demonstrate how format_xhs_result transforms actual XHS API responses.

Cleaning a Single Note

from agent_reach.channels.xiaohongshu import format_xhs_result

raw_note = {
    "id": "abc123",
    "title": "旅行日记",
    "desc": "在欧洲的美好瞬间",
    "type": "normal",
    "xsec_token": "tok_xyz",
    "user": {"nickname": "小红", "user_id": "u123", "avatar": "..."},
    "interact_info": {"liked_count": 10, "collected_count": 2},
    "image_list": [{"url": "https://img.example.com/1.jpg"}],
    "tag_list": [{"name": "旅行"}, {"name": "摄影"}],
}

clean = format_xhs_result(raw_note)
print(clean)

# {

#     "id": "abc123",

#     "title": "旅行日记",

#     "desc": "在欧洲的美好瞬间",

#     "type": "normal",

#     "xsec_token": "tok_xyz",

#     "user": {"nickname": "小红", "user_id": "u123"},

#     "liked_count": 10,

#     "collected_count": 2,

#     "images": ["https://img.example.com/1.jpg"],

#     "tags": ["旅行", "摄影"]

# }

Processing Search Result Containers

# Search feeds wrap results in an "items" key

raw_feed = {"items": [raw_note, raw_note]}
clean_list = format_xhs_result(raw_feed)

print(type(clean_list), len(clean_list))

# <class 'list'> 2

Handling Comments

raw_note_with_comments = dict(raw_note)
raw_note_with_comments["comments"] = [
    {
        "content": "写得真好!",
        "user_info": {"nickname": "路人甲"},
        "like_count": 5,
        "sub_comment_count": 1,
    }
]

clean = format_xhs_result(raw_note_with_comments)
print(clean["comments"][0])

# {"content": "写得真好!", "user": "路人甲", "like_count": 5, "sub_comment_count": 1}

Summary

• The format_xhs_result command in agent_reach/channels/xiaohongshu.py serves as the primary interface for cleaning XHS API responses.
• Input detection handles lists, dictionaries with container keys, and single objects automatically.
• Field normalization via _clean_note extracts only id, title, desc, user, engagement metrics, image URLs, and tags while discarding avatar data, tracking tokens, and structural metadata.
• Comment processing through _clean_comment further reduces nested comment trees to essential text and counts.
• Defensive pass-through ensures unexpected inputs don't crash the pipeline.
• Token reduction often exceeds 80%, significantly lowering costs when feeding XHS data into language models.

Frequently Asked Questions

Where is the format command implemented in Agent Reach?

The core logic resides in agent_reach/channels/xiaohongshu.py within the format_xhs_result function (lines 40–59). This function delegates note-level cleaning to _clean_note (lines 62–130) and comment processing to _clean_comment (lines 132–146). The formatter is part of the XiaoHongShuChannel class, which inherits from the base channel interface defined in agent_reach/channels/base.py.

Which fields does the formatter preserve from the Xiaohongshu API?

The formatter preserves core identifiers (id, note_id, xsec_token, title, desc, type, time), author data (nickname, user_id), engagement metrics (likes, collections, comments, shares), media URLs (from image_list), and tags. It also retains content as a fallback when desc is missing. All other metadata—including avatar URLs, tracking parameters, image dimensions, and raw user objects—is removed.

How does the formatter handle different XHS API endpoints?

The function detects container keys like "items" and "data" that wrap search results and feed arrays, automatically extracting the inner list for batch processing. For single-note endpoints (such as detail pages), it processes the dictionary directly. This design allows the same format_xhs_result call to work uniformly across search feeds, user profiles, and individual note lookups without requiring endpoint-specific configuration.

Can I use the format command outside of the Agent Reach CLI?

Yes. The format_xhs_result function is importable as a standalone utility from agent_reach.channels.xiaohongshu. You can pass any JSON-decoded XHS API response directly to this function in Python scripts, Jupyter notebooks, or custom pipelines. The function has no CLI dependencies and returns standard Python dictionaries or lists suitable for further processing or serialization.

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