# How the Agent Reach Format Command Cleans Xiaohongshu API JSON Output

> Learn how Agent Reach's format command cleans Xiaohongshu API JSON, compressing payloads by 80% via input detection, field normalization, and LLM data extraction. Boost efficiency today.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-14

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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

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

```python

# 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

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.