fix: #2061 handle invalid tool arguments JSON without crashing (#2337)

Author: seratch

src/agents/_run_impl.py

@@ -970,7 +970,7 @@ async def run_single_tool(
 
                     if rejected_message is not None:
                         # Input guardrail rejected the tool call
-                        final_result = rejected_message
+                        result = rejected_message
                     else:
                         # 2) Actually run the tool
                         real_result = await cls._execute_tool_with_hooks(
@@ -1001,7 +1001,7 @@ async def run_single_tool(
                                 else _coro.noop_coroutine()
                             ),
                         )
-                    result = final_result
+                        result = final_result
                 except Exception as e:
                     _error_tracing.attach_error_to_current_span(
                         SpanError(

src/agents/tool.py

@@ -668,8 +668,32 @@ def type(self) -> str:
 """A tool that can be used in an agent."""
 
 
+def _extract_json_decode_error(error: BaseException) -> json.JSONDecodeError | None:
+    current: BaseException | None = error
+    while current is not None:
+        if isinstance(current, json.JSONDecodeError):
+            return current
+        current = current.__cause__ or current.__context__
+    return None
+
+
+def _extract_tool_argument_json_error(error: Exception) -> json.JSONDecodeError | None:
+    if not isinstance(error, ModelBehaviorError):
+        return None
+    if not str(error).startswith("Invalid JSON input for tool"):
+        return None
+    return _extract_json_decode_error(error)
+
+
 def default_tool_error_function(ctx: RunContextWrapper[Any], error: Exception) -> str:
     """The default tool error function, which just returns a generic error message."""
+    json_decode_error = _extract_tool_argument_json_error(error)
+    if json_decode_error is not None:
+        return (
+            "An error occurred while parsing tool arguments. "
+            "Please try again with valid JSON. "
+            f"Error: {json_decode_error}"
+        )
     return f"An error occurred while running the tool. Please try again. Error: {str(error)}"
 
 
@@ -828,12 +852,20 @@ async def _on_invoke_tool(ctx: ToolContext[Any], input: str) -> Any:
                 if inspect.isawaitable(result):
                     return await result
 
+                json_decode_error = _extract_tool_argument_json_error(e)
+                if json_decode_error is not None:
+                    span_error_message = "Error running tool"
+                    span_error_detail = str(json_decode_error)
+                else:
+                    span_error_message = "Error running tool (non-fatal)"
+                    span_error_detail = str(e)
+
                 _error_tracing.attach_error_to_current_span(
                     SpanError(
-                        message="Error running tool (non-fatal)",
+                        message=span_error_message,
                         data={
                             "tool_name": schema.name,
-                            "error": str(e),
+                            "error": span_error_detail,
                         },
                     )
                 )

tests/test_run_step_execution.py

@@ -9,13 +9,16 @@
 from agents import (
     Agent,
     MessageOutputItem,
+    ModelBehaviorError,
     ModelResponse,
     RunConfig,
     RunContextWrapper,
     RunHooks,
     RunItem,
     ToolCallItem,
     ToolCallOutputItem,
+    ToolGuardrailFunctionOutput,
+    ToolInputGuardrail,
     TResponseInputItem,
     Usage,
 )
@@ -288,6 +291,64 @@ async def test_multiple_final_output_leads_to_final_output_next_step():
     assert result.next_step.output == Foo(bar="456")
 
 
+@pytest.mark.asyncio
+async def test_input_guardrail_runs_on_invalid_json():
+    guardrail_calls: list[str] = []
+
+    def guardrail(data) -> ToolGuardrailFunctionOutput:
+        guardrail_calls.append(data.context.tool_arguments)
+        return ToolGuardrailFunctionOutput.allow(output_info="checked")
+
+    guardrail_obj: ToolInputGuardrail[Any] = ToolInputGuardrail(guardrail_function=guardrail)
+
+    def _echo(value: str) -> str:
+        return value
+
+    tool = function_tool(
+        _echo,
+        name_override="guarded",
+        tool_input_guardrails=[guardrail_obj],
+    )
+    agent = Agent(name="test", tools=[tool])
+    response = ModelResponse(
+        output=[get_function_tool_call("guarded", "bad_json")],
+        usage=Usage(),
+        response_id=None,
+    )
+
+    result = await get_execute_result(agent, response)
+
+    assert guardrail_calls == ["bad_json"]
+    assert result.tool_input_guardrail_results
+    assert result.tool_input_guardrail_results[0].output.output_info == "checked"
+
+    output_item = next(
+        item for item in result.generated_items if isinstance(item, ToolCallOutputItem)
+    )
+    assert "An error occurred while parsing tool arguments" in str(output_item.output)
+
+
+@pytest.mark.asyncio
+async def test_invalid_json_raises_with_failure_error_function_none():
+    def _echo(value: str) -> str:
+        return value
+
+    tool = function_tool(
+        _echo,
+        name_override="guarded",
+        failure_error_function=None,
+    )
+    agent = Agent(name="test", tools=[tool])
+    response = ModelResponse(
+        output=[get_function_tool_call("guarded", "bad_json")],
+        usage=Usage(),
+        response_id=None,
+    )
+
+    with pytest.raises(ModelBehaviorError, match="Invalid JSON input for tool"):
+        await get_execute_result(agent, response)
+
+
 # === Helpers ===
 
 

tests/test_tracing_errors.py

@@ -13,7 +13,6 @@
     InputGuardrail,
     InputGuardrailTripwireTriggered,
     MaxTurnsExceeded,
-    ModelBehaviorError,
     RunContextWrapper,
     Runner,
     TResponseInputItem,
@@ -140,15 +139,22 @@ async def test_tool_call_error():
     agent = Agent(
         name="test_agent",
         model=model,
-        tools=[get_function_tool("foo", "tool_result", hide_errors=True)],
+        tools=[get_function_tool("foo", "tool_result")],
     )
 
-    model.set_next_output(
-        [get_text_message("a_message"), get_function_tool_call("foo", "bad_json")],
+    model.add_multiple_turn_outputs(
+        [
+            [get_text_message("a_message"), get_function_tool_call("foo", "bad_json")],
+            [get_text_message("done")],
+        ]
     )
 
-    with pytest.raises(ModelBehaviorError):
-        await Runner.run(agent, input="first_test")
+    result = await Runner.run(agent, input="first_test")
+
+    tool_outputs = [item for item in result.new_items if item.type == "tool_call_output_item"]
+    assert tool_outputs, "Expected a tool output item for invalid JSON"
+    assert "An error occurred while parsing tool arguments" in str(tool_outputs[0].output)
+    assert "valid JSON" in str(tool_outputs[0].output)
 
     assert fetch_normalized_spans() == snapshot(
         [
@@ -171,11 +177,20 @@ async def test_tool_call_error():
                                     "message": "Error running tool",
                                     "data": {
                                         "tool_name": "foo",
-                                        "error": "Invalid JSON input for tool foo: bad_json",
+                                        "error": "Expecting value: line 1 column 1 (char 0)",
                                     },
                                 },
-                                "data": {"name": "foo", "input": "bad_json"},
+                                "data": {
+                                    "name": "foo",
+                                    "input": "bad_json",
+                                    "output": (
+                                        "An error occurred while parsing tool arguments. "
+                                        "Please try again with valid JSON. Error: Expecting "
+                                        "value: line 1 column 1 (char 0)"
+                                    ),
+                                },
                             },
+                            {"type": "generation"},
                         ],
                     }
                 ],

tests/test_tracing_errors_streamed.py

@@ -14,7 +14,6 @@
     InputGuardrail,
     InputGuardrailTripwireTriggered,
     MaxTurnsExceeded,
-    ModelBehaviorError,
     OutputGuardrail,
     OutputGuardrailTripwireTriggered,
     RunContextWrapper,
@@ -149,17 +148,24 @@ async def test_tool_call_error():
     agent = Agent(
         name="test_agent",
         model=model,
-        tools=[get_function_tool("foo", "tool_result", hide_errors=True)],
+        tools=[get_function_tool("foo", "tool_result")],
     )
 
-    model.set_next_output(
-        [get_text_message("a_message"), get_function_tool_call("foo", "bad_json")],
+    model.add_multiple_turn_outputs(
+        [
+            [get_text_message("a_message"), get_function_tool_call("foo", "bad_json")],
+            [get_text_message("done")],
+        ]
     )
 
-    with pytest.raises(ModelBehaviorError):
-        result = Runner.run_streamed(agent, input="first_test")
-        async for _ in result.stream_events():
-            pass
+    result = Runner.run_streamed(agent, input="first_test")
+    async for _ in result.stream_events():
+        pass
+
+    tool_outputs = [item for item in result.new_items if item.type == "tool_call_output_item"]
+    assert tool_outputs, "Expected a tool output item for invalid JSON"
+    assert "An error occurred while parsing tool arguments" in str(tool_outputs[0].output)
+    assert "valid JSON" in str(tool_outputs[0].output)
 
     assert fetch_normalized_spans() == snapshot(
         [
@@ -182,11 +188,20 @@ async def test_tool_call_error():
                                     "message": "Error running tool",
                                     "data": {
                                         "tool_name": "foo",
-                                        "error": "Invalid JSON input for tool foo: bad_json",
+                                        "error": "Expecting value: line 1 column 1 (char 0)",
                                     },
                                 },
-                                "data": {"name": "foo", "input": "bad_json"},
+                                "data": {
+                                    "name": "foo",
+                                    "input": "bad_json",
+                                    "output": (
+                                        "An error occurred while parsing tool arguments. "
+                                        "Please try again with valid JSON. Error: Expecting "
+                                        "value: line 1 column 1 (char 0)"
+                                    ),
+                                },
                             },
+                            {"type": "generation"},
                         ],
                     }
                 ],