# Serialization and Deserialization Methods in hello-agents: JSON vs Pickle

> Explore serialization and deserialization methods in hello-agents, comparing JSON and Pickle for flexible agent state persistence and API communication.

- Repository: [Datawhale/hello-agents](https://github.com/datawhalechina/hello-agents)
- Tags: how-to-guide
- Published: 2026-05-09

---

**The hello-agents repository provides a unified utility module that supports both JSON and Pickle formats through the `serialize_object` and `deserialize_object` functions, enabling flexible data persistence for agent state and API communication.**

The `datawhalechina/hello-agents` repository implements a lightweight, format-agnostic serialization layer to handle data persistence across agent workflows. These **serialization/deserialization methods** are centralized in a dedicated utilities module, offering developers a consistent interface for converting Python objects into transportable formats and reconstructing them later.

## Core Serialization Utilities

The primary implementation resides in `Co‑creation‑projects/YYHDBL‑HelloCodeAgentCli/utils/serialization.py`. This module exports four public functions that wrap Python's standard library to provide a unified API:

- `serialize_object(obj, format="json")` — Converts Python objects to serialized strings or bytes
- `deserialize_object(data, format="json")` — Reconstructs Python objects from serialized data
- `save_to_file(obj, filepath, format="json")` — Persists objects directly to disk
- `load_from_file(filepath, format="json")` — Retrieves objects from disk files

These functions are re-exported through `Co‑creation‑projects/YYHDBL‑HelloCodeAgentCli/utils/__init__.py`, making them available via standard imports throughout the project.

### serialize_object and deserialize_object Implementation

According to the source code in [`serialization.py`](https://github.com/datawhalechina/hello-agents/blob/main/serialization.py), the `serialize_object` function selects the underlying implementation based on the `format` parameter:

- **JSON mode**: Uses `json.dumps(obj, ensure_ascii=False, indent=2)` to produce human-readable text
- **Pickle mode**: Uses `pickle.dumps(obj)` to generate binary representations of complex objects

The `deserialize_object` function reverses this process using `json.loads(data)` for text and `pickle.loads(data)` for binary streams.

### File Persistence Wrappers

The `save_to_file` and `load_from_file` functions handle disk I/O automatically. They select text mode (`"w"`/`"r"`) for JSON and binary mode (`"wb"`/`"rb"`) for Pickle, eliminating manual file handling boilerplate.

## Supported Serialization Formats

The utility supports two distinct **serialization/deserialization methods**, each suited to specific use cases within the agent ecosystem.

### JSON for Human-Readable Transport

JSON serves as the default format for API payloads, configuration persistence, and logging. The implementation ensures ASCII-compatible output with pretty-printing via `indent=2`. This format appears throughout the codebase in modules like [`code/chapter9/codebase_maintainer.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter9/codebase_maintainer.py) and [`code/chapter14/helloagents-deepresearch/.../agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter14/helloagents-deepresearch/.../agent.py), where direct `json.dumps(..., ensure_ascii=False)` calls handle event streaming and API communication.

### Pickle for Complex Python Objects

Pickle handles binary serialization for custom classes, nested objects, and non-JSON-serializable types. This method stores Python-specific object states that require exact reconstruction, including class instances with methods and complex data structures. Note that Pickle outputs are Python-version-specific and should only be used when the consumer environment matches the producer.

## Usage Examples

The following examples demonstrate practical implementations of these **serialization/deserialization methods**.

### Persisting Configuration Data

To serialize a dictionary to JSON and write it to disk:

```python
from YYHDBL_HelloCodeAgentCli.utils import save_to_file

payload = {"task": "summarise", "content": "Hello world"}
save_to_file(payload, "payload.json")  # Defaults to JSON format

```

Retrieve the data later using:

```python
from YYHDBL_HelloCodeAgentCli.utils import load_from_file

data = load_from_file("payload.json")
print(data["task"])  # Output: "summarise"

```

### Handling Custom Class Instances

For complex objects that cannot be represented in JSON, use the Pickle format:

```python
from YYHDBL_HelloCodeAgentCli.utils import serialize_object, deserialize_object

class Counter:
    def __init__(self, start=0):
        self.value = start
    
    def increment(self):
        self.value += 1

# Create and serialize

counter = Counter(5)
binary_data = serialize_object(counter, format="pickle")

# Deserialize and verify

restored = deserialize_object(binary_data, format="pickle")
print(restored.value)  # Output: 5

```

## Integration Across the Codebase

While the [`serialization.py`](https://github.com/datawhalechina/hello-agents/blob/main/serialization.py) module provides the canonical implementation, the repository also employs direct JSON serialization in various agent modules. Files such as [`code/chapter9/codebase_maintainer.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter9/codebase_maintainer.py) and deep research agents in `code/chapter14/helloagents-deepresearch/` utilize `json.dumps` for immediate API communication and structured logging, bypassing the utility wrappers when format flexibility is unnecessary.

## Summary

- The `hello-agents` repository centralizes **serialization/deserialization methods** in `Co‑creation‑projects/YYHDBL‑HelloCodeAgentCli/utils/serialization.py`
- Two formats are supported: **JSON** for text-based, interoperable data and **Pickle** for binary Python object persistence
- Four public functions (`serialize_object`, `deserialize_object`, `save_to_file`, `load_from_file`) provide a unified interface
- JSON serves API communication and logging throughout chapter-specific modules
- Pickle handles complex object states requiring exact Python reconstruction

## Frequently Asked Questions

### What file contains the main serialization logic in hello-agents?

The core logic resides in `Co‑creation‑projects/YYHDBL‑HelloCodeAgentCli/utils/serialization.py`. This file implements the `serialize_object` and `deserialize_object` functions that wrap Python's standard `json` and `pickle` libraries, along with file I/O helpers for persistent storage.

### When should I use Pickle instead of JSON in hello-agents?

Use **Pickle** when working with custom Python classes, objects containing non-serializable types (like `datetime` or complex nested structures), or when you need to preserve exact object state including methods. Use **JSON** for configuration files, API payloads, and any data requiring human readability or cross-language compatibility.

### How does the save_to_file function handle different formats?

The `save_to_file` function automatically selects text mode (`"w"`) for JSON and binary mode (`"wb"`) for Pickle based on the `format` parameter. It wraps the underlying serialization call and handles file opening, writing, and closing, returning `None` while persisting the serialized object to the specified filepath.

### Are the serialization utilities available throughout the entire project?

Yes. The `Co‑creation‑projects/YYHDBL‑HelloCodeAgentCli/utils/__init__.py` file re-exports `serialize_object` and `deserialize_object`, making them importable from the `utils` package. Additionally, the repository uses standard `json` operations directly in various agent modules for immediate serialization needs.