Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat: enhance JSON argument parsing and validation in CrewAgentExecutor and BaseTool
João Moura8102d0a6cade
diff --git a/lib/crewai/src/crewai/agents/crew_agent_executor.py b/lib/crewai/src/crewai/agents/crew_agent_executor.pyindex df51807f7..56abaae02 100644--- a/lib/crewai/src/crewai/agents/crew_agent_executor.py+++ b/lib/crewai/src/crewai/agents/crew_agent_executor.py@@ -50,6 +50,7 @@ from crewai.utilities.agent_utils import (handle_unknown_error,has_reached_max_iterations,is_context_length_exceeded,+ parse_tool_call_args,process_llm_response,track_delegation_if_needed,)@@ -894,13 +895,9 @@ class CrewAgentExecutor(CrewAgentExecutorMixin):ToolUsageStartedEvent,)- if isinstance(func_args, str):- try:- args_dict = json.loads(func_args)- except json.JSONDecodeError:- args_dict = {}- else:- args_dict = func_args+ args_dict, parse_error = parse_tool_call_args(func_args, func_name, call_id, original_tool)+ if parse_error is not None:+ return parse_errorif original_tool is None:for tool in self.original_tools or []:diff --git a/lib/crewai/src/crewai/experimental/agent_executor.py b/lib/crewai/src/crewai/experimental/agent_executor.pyindex 56c4da030..e568dc0d4 100644--- a/lib/crewai/src/crewai/experimental/agent_executor.py+++ b/lib/crewai/src/crewai/experimental/agent_executor.py@@ -66,6 +66,7 @@ from crewai.utilities.agent_utils import (has_reached_max_iterations,is_context_length_exceeded,is_inside_event_loop,+ parse_tool_call_args,process_llm_response,track_delegation_if_needed,)@@ -848,13 +849,9 @@ class AgentExecutor(Flow[AgentReActState], CrewAgentExecutorMixin):call_id, func_name, func_args = info# Parse arguments- if isinstance(func_args, str):- try:- args_dict = json.loads(func_args)- except json.JSONDecodeError:- args_dict = {}- else:- args_dict = func_args+ args_dict, parse_error = parse_tool_call_args(func_args, func_name, call_id)+ if parse_error is not None:+ return parse_error# Get agent_key for event trackingagent_key = getattr(self.agent, "key", "unknown") if self.agent else "unknown"diff --git a/lib/crewai/src/crewai/tools/base_tool.py b/lib/crewai/src/crewai/tools/base_tool.pyindex 8a10cdfa3..88c0826a9 100644--- a/lib/crewai/src/crewai/tools/base_tool.py+++ b/lib/crewai/src/crewai/tools/base_tool.py@@ -18,6 +18,7 @@ from pydantic import (BaseModel as PydanticBaseModel,ConfigDict,Field,+ ValidationError,create_model,field_validator,)@@ -150,14 +151,37 @@ class BaseTool(BaseModel, ABC):super().model_post_init(__context)+ def _validate_kwargs(self, kwargs: dict[str, Any]) -> dict[str, Any]:+ """Validate keyword arguments against args_schema if present.++ Args:+ kwargs: The keyword arguments to validate.++ Returns:+ Validated (and possibly coerced) keyword arguments.++ Raises:+ ValueError: If validation against args_schema fails.+ """+ if kwargs and self.args_schema is not None and self.args_schema.model_fields:+ try:+ validated = self.args_schema.model_validate(kwargs)+ return validated.model_dump()+ except Exception as e:+ raise ValueError(+ f"Tool '{self.name}' arguments validation failed: {e}"+ ) from e+ return kwargs+def run(self,*args: Any,**kwargs: Any,) -> Any:+ kwargs = self._validate_kwargs(kwargs)+result = self._run(*args, **kwargs)- # If _run is async, we safely run itif asyncio.iscoroutine(result):result = asyncio.run(result)@@ -179,6 +203,7 @@ class BaseTool(BaseModel, ABC):Returns:The result of the tool execution."""+ kwargs = self._validate_kwargs(kwargs)result = await self._arun(*args, **kwargs)self.current_usage_count += 1return result@@ -331,6 +356,8 @@ class Tool(BaseTool, Generic[P, R]):Returns:The result of the tool execution."""+ kwargs = self._validate_kwargs(kwargs)+result = self.func(*args, **kwargs)if asyncio.iscoroutine(result):@@ -361,6 +388,7 @@ class Tool(BaseTool, Generic[P, R]):Returns:The result of the tool execution."""+ kwargs = self._validate_kwargs(kwargs)result = await self._arun(*args, **kwargs)self.current_usage_count += 1return resultdiff --git a/lib/crewai/src/crewai/utilities/agent_utils.py b/lib/crewai/src/crewai/utilities/agent_utils.pyindex 80c80dbb6..7cad2ad67 100644--- a/lib/crewai/src/crewai/utilities/agent_utils.py+++ b/lib/crewai/src/crewai/utilities/agent_utils.py@@ -1146,6 +1146,36 @@ def extract_tool_call_info(return None+def parse_tool_call_args(+ func_args: dict[str, Any] | str,+ func_name: str,+ call_id: str,+ original_tool: Any = None,+) -> tuple[dict[str, Any], None] | tuple[None, dict[str, Any]]:+ """Parse tool call arguments from a JSON string or dict.++ Returns:+ ``(args_dict, None)`` on success, or ``(None, error_result)`` on+ JSON parse failure where ``error_result`` is a ready-to-return dict+ with the same shape as ``_execute_single_native_tool_call`` return values.+ """+ if isinstance(func_args, str):+ try:+ return json.loads(func_args), None+ except json.JSONDecodeError as e:+ return None, {+ "call_id": call_id,+ "func_name": func_name,+ "result": (+ f"Error: Failed to parse tool arguments as JSON: {e}. "+ f"Please provide valid JSON arguments for the '{func_name}' tool."+ ),+ "from_cache": False,+ "original_tool": original_tool,+ }+ return func_args, None++def _setup_before_llm_call_hooks(executor_context: CrewAgentExecutor | AgentExecutor | LiteAgent | None,printer: Printer,diff --git a/lib/crewai/tests/agents/test_native_tool_calling.py b/lib/crewai/tests/agents/test_native_tool_calling.pyindex 26b0a8e4a..558c34bb1 100644--- a/lib/crewai/tests/agents/test_native_tool_calling.py+++ b/lib/crewai/tests/agents/test_native_tool_calling.py@@ -11,7 +11,7 @@ import osimport threadingimport timefrom collections import Counter-from unittest.mock import patch+from unittest.mock import Mock, patchimport pytestfrom pydantic import BaseModel, Field@@ -1129,3 +1129,150 @@ class TestMaxUsageCountWithNativeToolCalling:# Verify the requested calls occurred while keeping usage bounded.assert tool.current_usage_count >= 2assert tool.current_usage_count <= tool.max_usage_count+++# =============================================================================+# JSON Parse Error Handling Tests+# =============================================================================+++class TestNativeToolCallingJsonParseError:+ """Tests that malformed JSON tool arguments produce clear errors+ instead of silently dropping all arguments."""++ def _make_executor(self, tools: list[BaseTool]) -> "CrewAgentExecutor":+ """Create a minimal CrewAgentExecutor with mocked dependencies."""+ from crewai.agents.crew_agent_executor import CrewAgentExecutor+ from crewai.tools.base_tool import to_langchain++ structured_tools = to_langchain(tools)+ mock_agent = Mock()+ mock_agent.key = "test_agent"+ mock_agent.role = "tester"+ mock_agent.verbose = False+ mock_agent.fingerprint = None+ mock_agent.tools_results = []++ mock_task = Mock()+ mock_task.name = "test"+ mock_task.description = "test"+ mock_task.id = "test-id"++ executor = object.__new__(CrewAgentExecutor)+ executor.agent = mock_agent+ executor.task = mock_task+ executor.crew = Mock()+ executor.tools = structured_tools+ executor.original_tools = tools+ executor.tools_handler = None+ executor._printer = Mock()+ executor.messages = []++ return executor++ def test_malformed_json_returns_parse_error(self) -> None:+ """Malformed JSON args must return a descriptive error, not silently become {}."""++ class CodeTool(BaseTool):+ name: str = "execute_code"+ description: str = "Run code"++ def _run(self, code: str) -> str:+ return f"ran: {code}"++ tool = CodeTool()+ executor = self._make_executor([tool])++ from crewai.utilities.agent_utils import convert_tools_to_openai_schema+ _, available_functions = convert_tools_to_openai_schema([tool])++ malformed_json = '{"code": "print("hello")"}'++ result = executor._execute_single_native_tool_call(+ call_id="call_123",+ func_name="execute_code",+ func_args=malformed_json,+ available_functions=available_functions,+ )++ assert "Failed to parse tool arguments as JSON" in result["result"]+ assert tool.current_usage_count == 0++ def test_valid_json_still_executes_normally(self) -> None:+ """Valid JSON args should execute the tool as before."""++ class CodeTool(BaseTool):+ name: str = "execute_code"+ description: str = "Run code"++ def _run(self, code: str) -> str:+ return f"ran: {code}"++ tool = CodeTool()+ executor = self._make_executor([tool])++ from crewai.utilities.agent_utils import convert_tools_to_openai_schema+ _, available_functions = convert_tools_to_openai_schema([tool])++ valid_json = '{"code": "print(1)"}'++ result = executor._execute_single_native_tool_call(+ call_id="call_456",+ func_name="execute_code",+ func_args=valid_json,+ available_functions=available_functions,+ )++ assert result["result"] == "ran: print(1)"++ def test_dict_args_bypass_json_parsing(self) -> None:+ """When func_args is already a dict, no JSON parsing occurs."""++ class CodeTool(BaseTool):+ name: str = "execute_code"+ description: str = "Run code"++ def _run(self, code: str) -> str:+ return f"ran: {code}"++ tool = CodeTool()+ executor = self._make_executor([tool])++ from crewai.utilities.agent_utils import convert_tools_to_openai_schema+ _, available_functions = convert_tools_to_openai_schema([tool])++ result = executor._execute_single_native_tool_call(+ call_id="call_789",+ func_name="execute_code",+ func_args={"code": "x = 42"},+ available_functions=available_functions,+ )++ assert result["result"] == "ran: x = 42"++ def test_schema_validation_catches_missing_args_on_native_path(self) -> None:+ """The native function calling path should now enforce args_schema,+ catching missing required fields before _run is called."""++ class StrictTool(BaseTool):+ name: str = "strict_tool"+ description: str = "A tool with required args"++ def _run(self, code: str, language: str) -> str:+ return f"{language}: {code}"++ tool = StrictTool()+ executor = self._make_executor([tool])++ from crewai.utilities.agent_utils import convert_tools_to_openai_schema+ _, available_functions = convert_tools_to_openai_schema([tool])++ result = executor._execute_single_native_tool_call(+ call_id="call_schema",+ func_name="strict_tool",+ func_args={"code": "print(1)"},+ available_functions=available_functions,+ )++ assert "Error" in result["result"]+ assert "validation failed" in result["result"].lower() or "missing" in result["result"].lower()diff --git a/lib/crewai/tests/tools/test_base_tool.py b/lib/crewai/tests/tools/test_base_tool.pyindex 4a6850ce1..a9d3a2b6d 100644--- a/lib/crewai/tests/tools/test_base_tool.py+++ b/lib/crewai/tests/tools/test_base_tool.py@@ -3,6 +3,8 @@ from typing import Callablefrom unittest.mock import patchimport pytest+from pydantic import BaseModel, Field+from crewai.agent import Agentfrom crewai.crew import Crewfrom crewai.task import Task@@ -230,3 +232,204 @@ def test_max_usage_count_is_respected():crew.kickoff()assert tool.max_usage_count == 5assert tool.current_usage_count == 5+++# =============================================================================+# Schema Validation in run() Tests+# =============================================================================+++class CodeExecutorInput(BaseModel):+ code: str = Field(description="The code to execute")+ language: str = Field(default="python", description="Programming language")+++class CodeExecutorTool(BaseTool):+ name: str = "code_executor"+ description: str = "Execute code snippets"+ args_schema: type[BaseModel] = CodeExecutorInput++ def _run(self, code: str, language: str = "python") -> str:+ return f"Executed {language}: {code}"+++class TestBaseToolRunValidation:+ """Tests for args_schema validation in BaseTool.run()."""++ def test_run_with_valid_kwargs_passes_validation(self) -> None:+ """Valid keyword arguments should pass schema validation and execute."""+ t = CodeExecutorTool()+ result = t.run(code="print('hello')")+ assert result == "Executed python: print('hello')"++ def test_run_with_all_kwargs_passes_validation(self) -> None:+ """All keyword arguments including optional ones should pass."""+ t = CodeExecutorTool()+ result = t.run(code="console.log('hi')", language="javascript")+ assert result == "Executed javascript: console.log('hi')"++ def test_run_with_missing_required_kwarg_raises(self) -> None:+ """Missing required kwargs should raise ValueError from schema validation."""+ t = CodeExecutorTool()+ with pytest.raises(ValueError, match="validation failed"):+ t.run(language="python")++ def test_run_with_wrong_field_name_raises(self) -> None:+ """Kwargs not matching any schema field should trigger validation error+ for missing required fields."""+ t = CodeExecutorTool()+ with pytest.raises(ValueError, match="validation failed"):+ t.run(wrong_arg="value")++ def test_run_with_positional_args_skips_validation(self) -> None:+ """Positional-arg calls should bypass schema validation (backwards compat)."""+ class SimpleTool(BaseTool):+ name: str = "simple"+ description: str = "A simple tool"++ def _run(self, question: str) -> str:+ return question++ t = SimpleTool()+ result = t.run("What is life?")+ assert result == "What is life?"++ def test_run_strips_extra_kwargs_from_llm(self) -> None:+ """Extra kwargs not in the schema should be silently stripped,+ preventing unexpected-keyword crashes in _run."""+ t = CodeExecutorTool()+ result = t.run(code="1+1", extra_hallucinated_field="junk")+ assert result == "Executed python: 1+1"++ def test_run_increments_usage_after_validation(self) -> None:+ """Usage count should still increment after validated execution."""+ t = CodeExecutorTool()+ assert t.current_usage_count == 0+ t.run(code="x = 1")+ assert t.current_usage_count == 1++ def test_run_does_not_increment_usage_on_validation_error(self) -> None:+ """Usage count should NOT increment when validation fails."""+ t = CodeExecutorTool()+ assert t.current_usage_count == 0+ with pytest.raises(ValueError):+ t.run(wrong="bad")+ assert t.current_usage_count == 0+++class TestToolDecoratorRunValidation:+ """Tests for args_schema validation in Tool.run() (decorator-based tools)."""++ def test_decorator_tool_run_validates_kwargs(self) -> None:+ """Decorator-created tools should also validate kwargs against schema."""+ @tool("execute_code")+ def execute_code(code: str, language: str = "python") -> str:+ """Execute a code snippet."""+ return f"Executed {language}: {code}"++ result = execute_code.run(code="x = 1")+ assert result == "Executed python: x = 1"++ def test_decorator_tool_run_rejects_missing_required(self) -> None:+ """Decorator tools should reject missing required args via validation."""+ @tool("execute_code")+ def execute_code(code: str) -> str:+ """Execute a code snippet."""+ return f"Executed: {code}"++ with pytest.raises(ValueError, match="validation failed"):+ execute_code.run(wrong_arg="value")++ def test_decorator_tool_positional_args_still_work(self) -> None:+ """Positional args to decorator tools should bypass validation."""+ @tool("greet")+ def greet(name: str) -> str:+ """Greet someone."""+ return f"Hello, {name}!"++ result = greet.run("World")+ assert result == "Hello, World!"+++# =============================================================================+# Async arun() Schema Validation Tests+# =============================================================================+++class AsyncCodeExecutorTool(BaseTool):+ name: str = "async_code_executor"+ description: str = "Execute code snippets asynchronously"+ args_schema: type[BaseModel] = CodeExecutorInput++ async def _arun(self, code: str, language: str = "python") -> str:+ return f"Async executed {language}: {code}"++ def _run(self, code: str, language: str = "python") -> str:+ return f"Executed {language}: {code}"+++class TestBaseToolArunValidation:+ """Tests for args_schema validation in BaseTool.arun()."""++ @pytest.mark.asyncio+ async def test_arun_with_valid_kwargs_passes_validation(self) -> None:+ """Valid keyword arguments should pass schema validation in arun."""+ t = AsyncCodeExecutorTool()+ result = await t.arun(code="print('hello')")+ assert result == "Async executed python: print('hello')"++ @pytest.mark.asyncio+ async def test_arun_with_missing_required_kwarg_raises(self) -> None:+ """Missing required kwargs should raise ValueError in arun."""+ t = AsyncCodeExecutorTool()+ with pytest.raises(ValueError, match="validation failed"):+ await t.arun(language="python")++ @pytest.mark.asyncio+ async def test_arun_with_wrong_field_name_raises(self) -> None:+ """Kwargs not matching schema fields should trigger validation error in arun."""+ t = AsyncCodeExecutorTool()+ with pytest.raises(ValueError, match="validation failed"):+ await t.arun(wrong_arg="value")++ @pytest.mark.asyncio+ async def test_arun_strips_extra_kwargs(self) -> None:+ """Extra kwargs not in the schema should be stripped in arun."""+ t = AsyncCodeExecutorTool()+ result = await t.arun(code="1+1", extra_field="junk")+ assert result == "Async executed python: 1+1"++ @pytest.mark.asyncio+ async def test_arun_does_not_increment_usage_on_validation_error(self) -> None:+ """Usage count should NOT increment when arun validation fails."""+ t = AsyncCodeExecutorTool()+ assert t.current_usage_count == 0+ with pytest.raises(ValueError):+ await t.arun(wrong="bad")+ assert t.current_usage_count == 0+++class TestToolDecoratorArunValidation:+ """Tests for args_schema validation in Tool.arun() (decorator-based async tools)."""++ @pytest.mark.asyncio+ async def test_async_decorator_tool_arun_validates_kwargs(self) -> None:+ """Async decorator tools should validate kwargs in arun."""+ @tool("async_execute")+ async def async_execute(code: str, language: str = "python") -> str:+ """Execute code asynchronously."""+ return f"Async {language}: {code}"++ result = await async_execute.arun(code="x = 1")+ assert result == "Async python: x = 1"++ @pytest.mark.asyncio+ async def test_async_decorator_tool_arun_rejects_missing_required(self) -> None:+ """Async decorator tools should reject missing required args in arun."""+ @tool("async_execute")+ async def async_execute(code: str) -> str:+ """Execute code asynchronously."""+ return f"Async: {code}"++ with pytest.raises(ValueError, match="validation failed"):+ await async_execute.arun(wrong_arg="value")diff --git a/lib/crewai/tests/utilities/test_agent_utils.py b/lib/crewai/tests/utilities/test_agent_utils.pyindex 31d7b9705..8e3093219 100644--- a/lib/crewai/tests/utilities/test_agent_utils.py+++ b/lib/crewai/tests/utilities/test_agent_utils.py@@ -17,6 +17,7 @@ from crewai.utilities.agent_utils import (_format_messages_for_summary,_split_messages_into_chunks,convert_tools_to_openai_schema,+ parse_tool_call_args,summarize_messages,)@@ -922,3 +923,56 @@ class TestParallelSummarizationVCR:assert summary_msg["role"] == "user"assert "files" in summary_msgassert "report.pdf" in summary_msg["files"]+++class TestParseToolCallArgs:+ """Unit tests for parse_tool_call_args."""++ def test_valid_json_string_returns_dict(self) -> None:+ args_dict, error = parse_tool_call_args('{"code": "print(1)"}', "run_code", "call_1")+ assert error is None+ assert args_dict == {"code": "print(1)"}++ def test_malformed_json_returns_error_dict(self) -> None:+ args_dict, error = parse_tool_call_args('{"code": "print("hi")"}', "run_code", "call_1")+ assert args_dict is None+ assert error is not None+ assert error["call_id"] == "call_1"+ assert error["func_name"] == "run_code"+ assert error["from_cache"] is False+ assert "Failed to parse tool arguments as JSON" in error["result"]+ assert "run_code" in error["result"]++ def test_malformed_json_preserves_original_tool(self) -> None:+ mock_tool = object()+ _, error = parse_tool_call_args("{bad}", "my_tool", "call_2", original_tool=mock_tool)+ assert error is not None+ assert error["original_tool"] is mock_tool++ def test_malformed_json_original_tool_defaults_to_none(self) -> None:+ _, error = parse_tool_call_args("{bad}", "my_tool", "call_3")+ assert error is not None+ assert error["original_tool"] is None++ def test_dict_input_returned_directly(self) -> None:+ func_args = {"code": "x = 42"}+ args_dict, error = parse_tool_call_args(func_args, "run_code", "call_4")+ assert error is None+ assert args_dict == {"code": "x = 42"}++ def test_empty_dict_input_returned_directly(self) -> None:+ args_dict, error = parse_tool_call_args({}, "run_code", "call_5")+ assert error is None+ assert args_dict == {}++ def test_valid_json_with_nested_values(self) -> None:+ args_dict, error = parse_tool_call_args(+ '{"query": "hello", "options": {"limit": 10}}', "search", "call_6"+ )+ assert error is None+ assert args_dict == {"query": "hello", "options": {"limit": 10}}++ def test_error_result_has_correct_keys(self) -> None:+ _, error = parse_tool_call_args("{bad json}", "tool", "call_7")+ assert error is not None+ assert set(error.keys()) == {"call_id", "func_name", "result", "from_cache", "original_tool"}