Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(blocks): add JSON encode and decode blocks (#13170)

Suraj Panickar7c41704c9dc6
diff --git a/autogpt_platform/backend/backend/blocks/json_blocks.py b/autogpt_platform/backend/backend/blocks/json_blocks.py
new file mode 100644
index 0000000000..bb5f276168
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/json_blocks.py
@@ -0,0 +1,89 @@
+"""JSON encode and decode blocks for processing structured data in workflows."""
+
+from typing import Any
+
+import orjson
+
+from backend.blocks._base import (
+ Block,
+ BlockCategory,
+ BlockOutput,
+ BlockSchemaInput,
+ BlockSchemaOutput,
+)
+from backend.data.model import SchemaField
+from backend.util.json import dumps, loads
+
+
+class JSONEncoderBlock(Block):
+
+ class Input(BlockSchemaInput):
+ data: Any = SchemaField(
+ description=(
+ "The data structure/value (object, list, string, etc.) to encode "
+ "into a JSON string."
+ ),
+ placeholder='e.g., {"key": "value"}',
+ )
+
+ class Output(BlockSchemaOutput):
+ json_str: str = SchemaField(
+ description="The JSON string representation of the input data."
+ )
+
+ def __init__(self):
+ super().__init__(
+ id="9a9d20c5-5b4d-4e94-8022-83b6cb72648a",
+ description="Encodes any value or data structure into a JSON string.",
+ categories={BlockCategory.DATA},
+ input_schema=JSONEncoderBlock.Input,
+ output_schema=JSONEncoderBlock.Output,
+ test_input={"data": {"name": "AutoGPT", "active": True}},
+ test_output=[
+ ("json_str", '{"name":"AutoGPT","active":true}'),
+ ],
+ )
+
+ async def run(self, input_data: Input, **kwargs) -> BlockOutput:
+ try:
+ json_str = dumps(input_data.data)
+ yield "json_str", json_str
+ except (orjson.JSONEncodeError, RecursionError, TypeError, ValueError) as e:
+ raise ValueError(f"JSON Encoding Error: {str(e)}") from e
+
+
+class JSONDecoderBlock(Block):
+
+ class Input(BlockSchemaInput):
+ json_str: str = SchemaField(
+ description="The JSON string to decode.",
+ placeholder='e.g., {"key": "value"}',
+ )
+
+ class Output(BlockSchemaOutput):
+ data: Any = SchemaField(
+ description="The value as decoded from the JSON string."
+ )
+
+ def __init__(self):
+ super().__init__(
+ id="2b935639-65bc-48fd-9f88-823cd706fcd9",
+ description=(
+ "Decodes a JSON string into the value or data structure, it "
+ "represents, e.g. an object, list, string, or number."
+ ),
+ categories={BlockCategory.DATA},
+ input_schema=JSONDecoderBlock.Input,
+ output_schema=JSONDecoderBlock.Output,
+ test_input={"json_str": '{"name":"AutoGPT","active":true}'},
+ test_output=[
+ ("data", {"name": "AutoGPT", "active": True}),
+ ],
+ )
+
+ async def run(self, input_data: Input, **kwargs) -> BlockOutput:
+ try:
+ parsed_data = loads(input_data.json_str)
+ yield "data", parsed_data
+ except orjson.JSONDecodeError as e:
+ raise ValueError(f"JSON Decoding Error: {str(e)}") from e
diff --git a/autogpt_platform/backend/backend/blocks/test/test_json_blocks.py b/autogpt_platform/backend/backend/blocks/test/test_json_blocks.py
new file mode 100644
index 0000000000..c7bafdb9fa
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/test/test_json_blocks.py
@@ -0,0 +1,175 @@
+import json
+
+import pytest
+
+from backend.blocks.json_blocks import JSONDecoderBlock, JSONEncoderBlock
+
+
+async def test_json_encoder_success():
+ block = JSONEncoderBlock()
+ data = {"hello": "world", "numbers": [1, 2, 3], "nested": {"key": True}}
+
+ outputs = []
+ async for output in block.run(JSONEncoderBlock.Input(data=data)):
+ outputs.append(output)
+
+ assert len(outputs) == 1
+ name, value = outputs[0]
+ assert name == "json_str"
+ parsed = json.loads(value)
+ assert parsed["hello"] == "world"
+ assert parsed["numbers"] == [1, 2, 3]
+ assert parsed["nested"]["key"] is True
+
+
+async def test_json_encoder_circular_reference():
+ block = JSONEncoderBlock()
+
+ data = {}
+ data["self"] = data
+
+ with pytest.raises(ValueError, match="JSON Encoding Error"):
+ async for _ in block.run(JSONEncoderBlock.Input(data=data)):
+ pass
+
+
+ "input_data",
+ [
+ "a string",
+ 42,
+ None,
+ [1, 2, "three"],
+ {},
+ [],
+ "",
+ ],
+)
+async def test_json_encoder_primitives(input_data):
+ block = JSONEncoderBlock()
+
+ outputs = []
+ async for output in block.run(JSONEncoderBlock.Input(data=input_data)):
+ outputs.append(output)
+
+ assert len(outputs) == 1
+ name, value = outputs[0]
+ assert name == "json_str"
+ # Compare semantic equality instead of raw formatting
+ assert json.loads(value) == input_data
+
+
+async def test_json_decoder_success():
+ block = JSONDecoderBlock()
+ json_str = '{"a": 1, "b": [true, false, null], "c": {"d": "nested"}}'
+
+ outputs = []
+ async for output in block.run(JSONDecoderBlock.Input(json_str=json_str)):
+ outputs.append(output)
+
+ assert len(outputs) == 1
+ name, value = outputs[0]
+ assert name == "data"
+ assert value == {"a": 1, "b": [True, False, None], "c": {"d": "nested"}}
+
+
+async def test_json_decoder_error():
+ block = JSONDecoderBlock()
+ # Malformed JSON string missing closing bracket
+ json_str = '{"a": 1, "b": [true, false,'
+
+ with pytest.raises(ValueError, match="JSON Decoding Error"):
+ async for _ in block.run(JSONDecoderBlock.Input(json_str=json_str)):
+ pass
+
+
+ "json_str,expected_data",
+ [
+ ('"a string"', "a string"),
+ ("42", 42),
+ ("null", None),
+ ('[1, 2, "three"]', [1, 2, "three"]),
+ ("{}", {}),
+ ("[]", []),
+ ('""', ""),
+ ],
+)
+async def test_json_decoder_primitives(json_str, expected_data):
+ block = JSONDecoderBlock()
+
+ outputs = []
+
+ async for output in block.run(JSONDecoderBlock.Input(json_str=json_str)):
+ outputs.append(output)
+
+ assert len(outputs) == 1
+ name, value = outputs[0]
+ assert name == "data"
+ assert value == expected_data
+
+
+ "invalid_float",
+ [
+ float("inf"),
+ float("-inf"),
+ float("nan"),
+ ],
+)
+async def test_json_encoder_non_finite_floats_become_null(invalid_float):
+ block = JSONEncoderBlock()
+ data = {"invalid": invalid_float}
+
+ outputs = []
+ async for output in block.run(JSONEncoderBlock.Input(data=data)):
+ outputs.append(output)
+
+ assert len(outputs) == 1
+ name, value = outputs[0]
+ assert name == "json_str"
+ parsed = json.loads(value)
+ assert parsed["invalid"] is None
+
+
+ "original_data",
+ [
+ {"name": "AutoGPT", "active": True},
+ [1, 2, 3, "test"],
+ "simple string",
+ 42,
+ None,
+ {"nested": {"list": [1, 2, None]}},
+ [],
+ {},
+ ],
+)
+async def test_json_roundtrip(original_data):
+ encoder = JSONEncoderBlock()
+ decoder = JSONDecoderBlock()
+
+ encoder_outputs = []
+ async for output in encoder.run(JSONEncoderBlock.Input(data=original_data)):
+ encoder_outputs.append(output)
+
+ assert len(encoder_outputs) == 1
+ name, json_str = encoder_outputs[0]
+ assert name == "json_str"
+
+ decoder_outputs = []
+ async for output in decoder.run(JSONDecoderBlock.Input(json_str=json_str)):
+ decoder_outputs.append(output)
+
+ assert len(decoder_outputs) == 1
+ name, decoded_data = decoder_outputs[0]
+ assert name == "data"
+ assert decoded_data == original_data
diff --git a/docs/integrations/README.md b/docs/integrations/README.md
index e9deaada1a..f0e5da3154 100644
--- a/docs/integrations/README.md
+++ b/docs/integrations/README.md
@@ -176,6 +176,8 @@ Below is a comprehensive list of all available blocks, categorized by their prim
| [Google Sheets Update Cell](block-integrations/google/sheets.md#google-sheets-update-cell) | Update a single cell in a Google Sheets spreadsheet |
| [Google Sheets Update Row](block-integrations/google/sheets.md#google-sheets-update-row) | Update a specific row by its index |
| [Google Sheets Write](block-integrations/google/sheets.md#google-sheets-write) | A block that writes data to a Google Sheets spreadsheet at a specified A1 notation range |
+| [JSON Decoder](block-integrations/data.md#json-decoder) | Decodes a JSON string into the value or data structure, it represents, e |
+| [JSON Encoder](block-integrations/data.md#json-encoder) | Encodes any value or data structure into a JSON string |
| [Keyword Suggestion Extractor](block-integrations/dataforseo/keyword_suggestions.md#keyword-suggestion-extractor) | Extract individual fields from a KeywordSuggestion object |
| [Persist Information](block-integrations/data.md#persist-information) | Persist key-value information for the current user |
| [Read Spreadsheet](block-integrations/data.md#read-spreadsheet) | Reads CSV and Excel files and outputs the data as a list of dictionaries and individual rows |
diff --git a/docs/integrations/block-integrations/data.md b/docs/integrations/block-integrations/data.md
index 4ee99c1340..67416d5280 100644
--- a/docs/integrations/block-integrations/data.md
+++ b/docs/integrations/block-integrations/data.md
@@ -118,6 +118,78 @@ Use skip_rows and skip_size to skip header content or initial bytes. When delimi
---
+## JSON Decoder
+
+### What it is
+Decodes a JSON string into the value or data structure, it represents, e.g. an object, list, string, or number.
+
+### How it works
+<!-- MANUAL: how_it_works -->
+This block uses the project's `orjson`-based decoder to parse a JSON-formatted string and safely convert it into native Python data structures. Valid inputs must strictly follow JSON syntax; for example, passing the string `'{"active": true, "val": null}'` will successfully decode into a Python dictionary where JSON's `true` maps to the Python boolean `True` and `null` maps to `None`.
+
+If the input string is malformed or contains invalid JSON syntax (such as missing quotes or trailing commas), the internal parser throws an exception. The block catches this exception and raises a `ValueError` that aborts the block execution, integrating with the framework's execution error handling. The legacy schema-level error pin is unused. Edge cases like empty strings or deeply nested structures are handled securely, though extremely deep nesting may be limited by standard parsing recursion depths.
+<!-- END MANUAL -->
+
+### Inputs
+
+| Input | Description | Type | Required |
+|-------|-------------|------|----------|
+| json_str | The JSON string to decode. | str | Yes |
+
+### Outputs
+
+| Output | Description | Type |
+|--------|-------------|------|
+| error | Error message if the operation failed | str |
+| data | The value as decoded from the JSON string. | Data |
+
+### Possible use case
+<!-- MANUAL: use_case -->
+**API Response Processing**: Parse JSON responses from external APIs into structured data for further processing in your workflow.
+
+**Configuration Loading**: Decode JSON-formatted configuration strings into accessible dictionary settings for your agents.
+
+**Webhook Payload Parsing**: Extract nested fields from incoming JSON webhook payloads for dynamic decision-making.
+<!-- END MANUAL -->
+
+---
+
+## JSON Encoder
+
+### What it is
+Encodes any value or data structure into a JSON string.
+
+### How it works
+<!-- MANUAL: how_it_works -->
+This block serializes standard Python structures (like `dict`, `list`, `str`, `int`, `float`, `bool`, and `None`) into a valid JSON string using the project's optimized `orjson`-based encoder. It safely handles nested structures, automatically converting Python equivalents to their JSON counterparts (e.g., `{"a": 1}` remains an object, and `None` is translated to `null`).
+
+Before outputting, the block validates JSON-serializability. If an unsupported type is provided—such as custom objects, `datetime`, or `set`s without custom serialization—it raises a `ValueError` that aborts the block execution, integrating with the framework's execution error handling. The legacy schema-level error pin is unused. For edge cases like large numeric precision or non-serializable types, it is recommended to pre-convert these values into strings or dictionaries before passing them to the encoder.
+<!-- END MANUAL -->
+
+### Inputs
+
+| Input | Description | Type | Required |
+|-------|-------------|------|----------|
+| data | The data structure/value (object, list, string, etc.) to encode into a JSON string. | Data | Yes |
+
+### Outputs
+
+| Output | Description | Type |
+|--------|-------------|------|
+| error | Error message if the operation failed | str |
+| json_str | The JSON string representation of the input data. | str |
+
+### Possible use case
+<!-- MANUAL: use_case -->
+**API Request Formatting**: Convert Python dictionaries into JSON strings for POST/PUT request bodies.
+
+**Data Export**: Serialize structured workflow data into JSON format for saving to files or persistent storage.
+
+**Log Structured Data**: Encode complex data structures into JSON strings for structured logging and debugging output.
+<!-- END MANUAL -->
+
+---
+
## Persist Information
### What it is