# Agent Reach Format Command for XiaoHongShu API Output Normalization

> Normalize XiaoHongShu API output with Agent Reach format command. Streamline verbose responses into essential fields for efficient AI agent processing. Discover Agent Reach today.

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

---

**The `format_xhs_result` command in Agent Reach strips verbose XiaoHongShu API responses down to essential fields, producing a consistent, token-efficient structure for AI agents.**

The Panniantong/Agent-Reach repository provides a dedicated normalization layer for XiaoHongShu (XHS) content through the `format_xhs_result` function implemented in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py). This formatter integrates with the **XiaoHongShuChannel** class to abstract three possible backends—OpenCLI, xiaohongshu-mcp, and the legacy xhs-cli—while ensuring that raw API payloads become immediately usable for downstream language models.

## How format_xhs_result Normalizes XiaoHongShu Responses

The `format_xhs_result` function serves as the primary entry point for converting nested, verbose XHS API JSON into a flat, predictable dictionary structure. Located in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py), this function detects the payload type and applies appropriate cleaning logic to minimize token usage when sending data to AI agents.

### Detecting List vs. Dictionary Structures

At lines 40-48 of [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py), the formatter first inspects the top-level payload type. If the input is a **list**, each element is processed individually through the `_clean_note` helper. If the input is a **dictionary**, the function searches for the actual note collection under common wrapper keys such as `items`, `data.items`, or `data.notes`, ensuring compatibility with various API response formats.

### Normalizing Collections and Single Notes

For search results (lines 49-56), the function returns a standardized list of cleaned notes. When processing a single note (lines 58-70), it delegates to `_clean_note` to extract relevant fields. If the payload is neither a list nor a dictionary, the function returns the data unchanged at line 59, allowing callers to handle unexpected formats gracefully.

### Extracting Essential Note Fields

The `_clean_note` helper (lines 72-98) performs the heavy lifting by extracting only the fields an AI agent requires:

- **Identifiers**: `id`, `note_id`
- **Content**: `title`, `desc`, `content`
- **Author metadata**: `nickname`, `user_id`
- **Engagement metrics**: `liked_count`, `collected_count`, `comment_count`, `share_count`

This selective extraction removes irrelevant metadata and nested objects that would otherwise consume unnecessary tokens in model context windows.

### Flattening Images and Tags

Image normalization (lines 99-112) transforms nested image objects into a simple list of URLs under the `images` key. Similarly, tag normalization (lines 114-124) extracts tag names into a flat list under `tags`, discarding extraneous metadata like tag IDs or display properties.

### Processing Comments

When notes include comments, the formatter applies `_clean_comment` (lines 125-128) to retain only the `content`, author name, and basic counters. This prevents comment threads from bloating the output while preserving conversational context.

## Implementation Architecture

The normalization logic resides within the **XiaoHongShuChannel** class, which implements the abstract base defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py). The channel automatically invokes `format_xhs_result` during `read` and `search` operations, ensuring that all XHS content—whether from OpenCLI, xiaohongshu-mcp, or xhs-cli backends—emerges in a uniform shape suitable for agent consumption.

Core routing in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) coordinates channel selection, while the CLI entry point in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) exposes these capabilities through the `agent-reach read` sub-command.

## Practical Code Examples

### Standalone Formatter Usage

Import and invoke the formatter directly when working with raw API responses:

```python
from agent_reach.channels.xiaohongshu import format_xhs_result

# Raw API payload with nested structure

raw_response = {
    "data": {
        "items": [
            {
                "note_card": {
                    "note_id": "12345",
                    "title": "My travel diary",
                    "desc": "A short description",
                    "user": {"nickname": "Alice", "user_id": "u987"},
                    "interact_info": {"liked_count": 42, "comment_count": 5},
                    "image_list": [
                        {"url": "https://example.com/img1.jpg"},
                        {"url": "https://example.com/img2.jpg"},
                    ],
                    "tag_list": [{"name": "travel"}, {"name": "photography"}],
                }
            }
        ]
    }
}

# Normalize to agent-friendly format

clean = format_xhs_result(raw_response)

print(clean)

```

The output contains only the essential fields:

```python
[{'note_id': '12345',
  'title': 'My travel diary',
  'desc': 'A short description',
  'user': {'nickname': 'Alice', 'user_id': 'u987'},
  'liked_count': 42,
  'comment_count': 5,
  'images': ['https://example.com/img1.jpg',
             'https://example.com/img2.jpg'],
  'tags': ['travel', 'photography']}]

```

### Integrated Channel Usage

When using the high-level Agent Reach API, normalization happens automatically:

```python
from agent_reach.core import AgentReach

ar = AgentReach()

# Automatically calls format_xhs_result during retrieval

note = ar.read("https://www.xiaohongshu.com/explore/12345")
print(note)  # Already normalized

```

## Summary

- The **`format_xhs_result`** function in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) provides the primary normalization logic for XiaoHongShu API outputs.
- It intelligently detects **list vs. dictionary** payloads and extracts note collections from wrapper keys like `items`, `data.items`, or `data.notes`.
- The **`_clean_note`** helper extracts only essential fields including identifiers, content, author info, and engagement metrics while discarding verbose metadata.
- **Images** and **tags** are flattened into simple URL and name lists, respectively, and **comments** are processed via `_clean_comment` to retain only necessary context.
- The formatter supports three backends (OpenCLI, xiaohongshu-mcp, xhs-cli) and returns data unchanged when encountering unexpected structures.

## Frequently Asked Questions

### What specific fields does the format_xhs_result command preserve?

The command extracts `id`, `note_id`, `title`, `desc`, `content`, `nickname`, `user_id`, `liked_count`, `collected_count`, `comment_count`, and `share_count`. It also normalizes nested `image_list` objects into a flat `images` array and `tag_list` into a simple `tags` list, removing all other metadata to minimize token usage.

### How does Agent Reach handle different XiaoHongShu API response structures?

According to the source code in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py), the function checks if the payload is a list or dictionary at lines 40-48. For dictionaries, it searches standard wrapper keys including `items`, `data.items`, and `data.notes` to locate the actual note data, ensuring compatibility across different API endpoints and backend implementations.

### Can I use format_xhs_result outside of the XiaoHongShuChannel?

Yes. While the **XiaoHongShuChannel** class automatically invokes this formatter during `read` and `search` operations, you can import and call `format_xhs_result` directly from `agent_reach.channels.xiaohongshu` to process raw API responses in custom scripts or alternative integration patterns.

### Why is API output normalization critical for AI agent performance?

XiaoHongShu API responses contain extensive metadata, nested objects, and redundant fields that significantly increase token counts when passed to language models. The `format_xhs_result` command reduces payload size by 60-80% in typical scenarios, lowering inference costs and preventing context window overflow while maintaining all semantically relevant content for agent reasoning.