agentscope-ai/agentscope · error · ToolJSONDecodeError

<system-reminder>{error_message} Your argument string is de

Error message

<system-reminder>{error_message}

Your argument string is decoded by the following code snippet{ellipsis_hint}:
```python
import json

your_tool_arguments = {repr(error_json_str)}
json.loads(your_tool_arguments)
```

**You should recorrect the arguments in JSON format.**</system-reminder>

What it means

When an agent emits tool-call arguments as a malformed or truncated JSON string, agentscope attempts a repair (_json_loads_with_repair). If repair fails, it raises ToolJSONDecodeError with a <system-reminder> prompt that is meant to be fed back to the LLM so it re-emits valid JSON arguments. This is an intentional error-feedback loop for structured tool calling.

Source

Thrown at src/agentscope/_utils/_common.py:152

    except Exception:
        # Whatever the error is, we throw the original error message to the
        # agent, which is more helpful for debugging.
        pass

    # If still failed, we throw the original error message to the agent, rather
    # than the error from json_repair, which is less helpful for debugging.
    if len(json_str) > 200:
        error_json_str = json_str[:100] + "[TRUNCATE]" + json_str[-100:]
        ellipsis_hint = (
            "(Because the JSON string is too long, a truncated label "
            '"[TRUNCATE]" is used here to indicate the truncation)'
        )
    else:
        error_json_str = json_str
        ellipsis_hint = ""

    raise ToolJSONDecodeError(
        f"""<system-reminder>{error_message}

Your argument string is decoded by the following code snippet{ellipsis_hint}:
```python
import json

your_tool_arguments = {repr(error_json_str)}
json.loads(your_tool_arguments)
```

**You should recorrect the arguments in JSON format.**</system-reminder>""",
    )


def _get_timestamp(add_random_suffix: bool = False) -> str:
    """Get the current timestamp in the format YYYY-MM-DD HH:MM:SS.sss."""
    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]

View on GitHub (pinned to e90f1c7592)

Solutions

Catch ToolJSONDecodeError and send the error message (the <system-reminder> text) back to the model so it corrects the arguments
Reduce tool argument size (fewer/shorter parameters) to avoid truncation; increase the model's max output tokens
Switch to a model with stronger native function-calling/JSON mode
Simplify the tool schema — fewer required fields, shorter enums/descriptions

Example fix

# before
tool_args = json.loads(msg.get_tool_args())  # raises raw JSONDecodeError

# after
from agentscope.exception import ToolJSONDecodeError
try:
    tool_args = json.loads(msg.get_tool_args())
except (ToolJSONDecodeError, json.JSONDecodeError) as e:
    # feed the reminder back to the agent for correction
    await agent.observe(Msg("system", str(e), role="system"))
    msg = await agent.reply()

Defensive patterns

Strategy: retry

Validate before calling

def try_parse_tool_args(raw: str) -> dict | None:
    try:
        return json.loads(raw)
    except json.JSONDecodeError:
        return None

args = try_parse_tool_args(msg.get_tool_args())
if args is None:
    # ask the model to re-emit instead of letting the pipeline raise
    ...

Type guard

import json
from typing import TypeGuard, Any

def is_valid_tool_args(raw: str) -> TypeGuard[str]:
    try:
        json.loads(raw)
        return True
    except json.JSONDecodeError:
        return False

Try / catch

from agentscope.exception import ToolJSONDecodeError

try:
    result = json.loads(tool_args_str)
except ToolJSONDecodeError as e:
    # e's message is designed to be shown back to the model
    await agent.observe(Msg("system", str(e), role="system"))
    corrected = await agent.reply()
    result = json.loads(corrected.get_tool_args())

Prevention

Keep tool argument payloads small to avoid truncation-induced invalid JSON
Prefer models with native function calling / JSON mode
Always have a correction loop: catch the error and re-prompt rather than crashing the run
Validate JSON before dispatching to tool implementation

When it happens

Trigger: A model returns tool arguments with unescaped quotes/newlines, single quotes instead of double quotes, or output truncated at max length (the message then includes the '"[TRUNCATE]"' hint). Calling the internal JSON repair path with such a string triggers this exception.

Common situations: Weaker or smaller models producing non-strict JSON, long tool arguments hitting token limits causing truncation, nested quotes in string values, or non-ASCII/unescaped characters. Frequently seen with function-calling on models not fine-tuned for strict JSON.

Related errors

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/fc0897eb6df0431d. Report an issue: GitHub.