Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
Add typed output schemas for CrewAI tools (#6236)
Vinicius Brasil9db2d4476641
diff --git a/docs/edge/en/concepts/tools.mdx b/docs/edge/en/concepts/tools.mdxindex 52e568073..da41da3b1 100644--- a/docs/edge/en/concepts/tools.mdx+++ b/docs/edge/en/concepts/tools.mdx@@ -39,6 +39,7 @@ The Enterprise Tools Repository includes:- **Error Handling**: Incorporates robust error handling mechanisms to ensure smooth operation.- **Caching Mechanism**: Features intelligent caching to optimize performance and reduce redundant operations.- **Asynchronous Support**: Handles both synchronous and asynchronous tools, enabling non-blocking operations.+- **Typed Outputs**: Uses optional Pydantic models to give agents clear JSON fields while direct Python calls still receive the tool's normal return value.## Using CrewAI Tools@@ -184,6 +185,55 @@ class MyCustomTool(BaseTool):return "Tool's result"```+### Typed Tool Outputs++When a tool returns structured data, define a Pydantic output model. This gives the agent field names it can trust, such as `sku`, `quantity`, or `needs_reorder`.++Direct Python calls still receive the value your tool returns. When an agent uses the tool, CrewAI sends the agent a JSON string based on the output model.++```python Code+from crewai.tools import BaseTool+from pydantic import BaseModel++class InventoryResult(BaseModel):+ sku: str+ quantity: int+ needs_reorder: bool++class InventoryTool(BaseTool):+ name: str = "Inventory Check"+ description: str = "Checks current stock for a product SKU."++ def _run(self, sku: str) -> InventoryResult:+ quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)+ return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)++tool = InventoryTool()++# Direct calls receive the raw Pydantic object.+result = tool.run(sku="SKU-123")+print(result.quantity)+```++To send Markdown or another short text format to the agent, override `format_output_for_agent`. Direct calls to `tool.run(...)` still return the normal Python value.++```python Code+class InventoryTool(BaseTool):+ name: str = "Inventory Check"+ description: str = "Checks current stock for a product SKU."++ def _run(self, sku: str) -> InventoryResult:+ quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)+ return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)++ def format_output_for_agent(self, raw_result: object) -> str:+ result = InventoryResult.model_validate(raw_result)+ status = "reorder needed" if result.needs_reorder else "stock is healthy"+ return f"{result.sku}: {result.quantity} units. {status}."+```++If you do not override `format_output_for_agent`, typed outputs are sent to the agent as JSON. Plain string results work as before.+## Asynchronous Tool SupportCrewAI supports asynchronous tools, allowing you to implement tools that perform non-blocking operations like network requests, file I/O, or other async operations without blocking the main execution thread.diff --git a/docs/edge/en/guides/tools/publish-custom-tools.mdx b/docs/edge/en/guides/tools/publish-custom-tools.mdxindex 973856816..71dbfd622 100644--- a/docs/edge/en/guides/tools/publish-custom-tools.mdx+++ b/docs/edge/en/guides/tools/publish-custom-tools.mdx@@ -65,7 +65,7 @@ Regardless of which approach you use, your tool must:- Have a **`description`** — tells the agent when and how to use the tool. This directly affects how well agents use your tool, so be clear and specific.- Implement **`_run`** (BaseTool) or provide a **function body** (@tool) — the synchronous execution logic.- Use **type annotations** on all parameters and return values.-- Return a **string** result (or something that can be meaningfully converted to one).+- Return a **string** result, or define an optional Pydantic output schema for structured results.### Optional: Async Support@@ -104,6 +104,67 @@ class TranslateInput(BaseModel):Explicit schemas are recommended for published tools — they produce better agent behavior and clearer documentation for your users.+### Optional: Typed Outputs with `result_schema`++If your tool returns structured data, define a Pydantic output model. This is a good default for published tools because users and agents can rely on named fields.++Direct Python calls still receive the value your tool returns. When an agent uses the tool, CrewAI sends the agent JSON based on the output model.++CrewAI can infer the output schema from a Pydantic return annotation:++```python+from crewai.tools import BaseTool+from pydantic import BaseModel, Field+++class GeolocateResult(BaseModel):+ latitude: float = Field(..., description="Latitude in decimal degrees.")+ longitude: float = Field(..., description="Longitude in decimal degrees.")+++class GeolocateTool(BaseTool):+ name: str = "Geolocate"+ description: str = "Converts a street address into latitude/longitude coordinates."++ def _run(self, address: str) -> GeolocateResult:+ if "1600 Pennsylvania" in address:+ return GeolocateResult(latitude=38.8977, longitude=-77.0365)+ return GeolocateResult(latitude=40.7128, longitude=-74.0060)+```++Set `result_schema` explicitly when your tool returns a dictionary:++```python+class GeolocateTool(BaseTool):+ name: str = "Geolocate"+ description: str = "Converts a street address into latitude/longitude coordinates."+ result_schema: type[BaseModel] = GeolocateResult++ def _run(self, address: str) -> dict[str, float]:+ if "1600 Pennsylvania" in address:+ return {"latitude": 38.8977, "longitude": -77.0365}+ return {"latitude": 40.7128, "longitude": -74.0060}+```++If agents should receive a short text summary instead of JSON, override `format_output_for_agent` on your `BaseTool` subclass.++```python+class GeolocateTool(BaseTool):+ name: str = "Geolocate"+ description: str = "Converts a street address into latitude/longitude coordinates."++ def _run(self, address: str) -> GeolocateResult:+ if "1600 Pennsylvania" in address:+ return GeolocateResult(latitude=38.8977, longitude=-77.0365)+ return GeolocateResult(latitude=40.7128, longitude=-74.0060)++ def format_output_for_agent(self, raw_result: object) -> str:+ result = GeolocateResult.model_validate(raw_result)+ return f"Latitude {result.latitude}, longitude {result.longitude}"+```++The override only changes what the agent sees. Direct users of your package still receive the normal value from `tool.run(...)`.+### Optional: Environment VariablesIf your tool requires API keys or other configuration, declare them with `env_vars` so users know what to set:@@ -241,4 +302,4 @@ agent = Agent(tools=[GeolocateTool()],# ...)-```\ No newline at end of file+```diff --git a/docs/edge/en/learn/create-custom-tools.mdx b/docs/edge/en/learn/create-custom-tools.mdxindex c1246f3fc..78205bf99 100644--- a/docs/edge/en/learn/create-custom-tools.mdx+++ b/docs/edge/en/learn/create-custom-tools.mdx@@ -53,6 +53,111 @@ def my_simple_tool(question: str) -> str:return "Tool output"```+### Best Practice: Define Typed Outputs++When a tool returns structured data, define a Pydantic output model. This helps the agent read the result as clear fields instead of guessing from plain text.++Typed outputs are useful for results with stable fields, such as IDs, status values, scores, prices, or lists. Plain strings are still fine for short prose results.++Direct Python calls still receive the value your tool returns. When an agent uses a typed tool, CrewAI sends the agent JSON based on the output model.++#### Return a Pydantic Model++CrewAI infers the output schema when your `BaseTool` has a Pydantic return annotation.++```python Code+from crewai.tools import BaseTool+from pydantic import BaseModel, Field++class InventoryResult(BaseModel):+ sku: str = Field(description="The product SKU.")+ quantity: int = Field(description="Units available.")+ needs_reorder: bool = Field(description="Whether the item should be reordered.")++class InventoryTool(BaseTool):+ name: str = "Inventory Check"+ description: str = "Check current stock for a product SKU."++ def _run(self, sku: str) -> InventoryResult:+ quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)+ return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)++tool = InventoryTool()+result = tool.run(sku="SKU-123")++# Direct Python calls receive the raw Pydantic object.+print(result.quantity)+```++When an agent calls `InventoryTool`, it receives JSON like this:++```json+{"sku":"SKU-123","quantity":14,"needs_reorder":false}+```++#### Use `result_schema` with Dictionary Results++If your tool returns a dictionary, set `result_schema` explicitly. You can do this on a `BaseTool` subclass or with the `@tool` decorator:++```python Code+from crewai.tools import tool+from pydantic import BaseModel, Field++class ProductResult(BaseModel):+ sku: str = Field(description="The product SKU.")+ name: str = Field(description="The product name.")+ in_stock: bool = Field(description="Whether the product is available.")++@tool("Product Lookup", result_schema=ProductResult)+def product_lookup(sku: str) -> dict[str, object]:+ """Look up product availability by SKU."""+ catalog = {+ "SKU-123": ("Noise-canceling headset", True),+ "SKU-456": ("USB-C dock", False),+ }+ name, in_stock = catalog.get(sku, ("Unknown product", False))+ return {+ "sku": sku,+ "name": name,+ "in_stock": in_stock,+ }+```++#### Customize the Text Sent to the Agent++By default, typed tool outputs are sent to the agent as JSON. If the agent should receive a short summary instead, subclass `BaseTool` and override `format_output_for_agent`.++```python Code+from crewai.tools import BaseTool+from pydantic import BaseModel, Field++class InventoryResult(BaseModel):+ sku: str = Field(description="The product SKU.")+ quantity: int = Field(description="Units available.")+ needs_reorder: bool = Field(description="Whether the item should be reordered.")++class InventoryTool(BaseTool):+ name: str = "Inventory Check"+ description: str = "Check current stock for a product SKU."++ def _run(self, sku: str) -> InventoryResult:+ quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0)+ return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5)++ def format_output_for_agent(self, raw_result: object) -> str:+ result = InventoryResult.model_validate(raw_result)+ status = "reorder needed" if result.needs_reorder else "stock is healthy"+ return f"{result.sku}: {result.quantity} units. {status}."++tool = InventoryTool()+result = tool.run(sku="SKU-123")++# Direct Python calls receive the raw Pydantic object.+print(result.quantity)+```++The override only changes what the agent sees. Direct calls to `tool.run(...)` still return the normal Python value.+### Defining a Cache Function for the ToolTo optimize tool performance with caching, define custom caching strategies using the `cache_function` attribute.diff --git a/docs/edge/en/learn/execution-hooks.mdx b/docs/edge/en/learn/execution-hooks.mdxindex 74234db97..f9f667e4f 100644--- a/docs/edge/en/learn/execution-hooks.mdx+++ b/docs/edge/en/learn/execution-hooks.mdx@@ -195,9 +195,12 @@ class ToolCallHookContext:agent: Agent | None # Agent executingtask: Task | None # Current taskcrew: Crew | None # Crew instance- tool_result: str | None # Tool result (after hooks)+ tool_result: str | None # Agent-facing result string (after hooks)+ raw_tool_result: Any | None # Raw Python result (after hooks)```+For typed tool outputs, `tool_result` is the string the agent sees. By default, this is JSON. If the tool uses custom formatting, it can be Markdown or another string. `raw_tool_result` is the original Python value returned by the tool.+## Common Patterns### Safety and Validationdiff --git a/docs/edge/en/learn/tool-hooks.mdx b/docs/edge/en/learn/tool-hooks.mdxindex d1d727a5c..489463e81 100644--- a/docs/edge/en/learn/tool-hooks.mdx+++ b/docs/edge/en/learn/tool-hooks.mdx@@ -60,9 +60,12 @@ class ToolCallHookContext:agent: Agent | BaseAgent | None # Agent executing the tooltask: Task | None # Current taskcrew: Crew | None # Crew instance- tool_result: str | None # Tool result (after hooks only)+ tool_result: str | None # Agent-facing result string (after hooks only)+ raw_tool_result: Any | None # Raw Python result (after hooks only)```+For typed tool outputs, `tool_result` is the string the agent sees. By default, this is JSON. If the tool uses custom formatting, it can be Markdown or another string. Use `raw_tool_result` when your hook needs the typed object or dictionary.+### Modifying Tool Inputs**Important:** Always modify tool inputs in-place:diff --git a/lib/crewai/src/crewai/agents/crew_agent_executor.py b/lib/crewai/src/crewai/agents/crew_agent_executor.pyindex 92a1ce5fb..de2315e3a 100644--- a/lib/crewai/src/crewai/agents/crew_agent_executor.py+++ b/lib/crewai/src/crewai/agents/crew_agent_executor.py@@ -57,6 +57,7 @@ from crewai.utilities.agent_utils import (convert_tools_to_openai_schema,enforce_rpm_limit,format_message_for_llm,+ format_native_tool_output_for_agent,get_llm_response,handle_agent_action_core,handle_context_length,@@ -907,19 +908,31 @@ class CrewAgentExecutor(BaseAgentExecutor):):max_usage_reached = True+ structured_tool: CrewStructuredTool | None = None+ if original_tool is not None:+ for structured in self.tools or []:+ if getattr(structured, "_original_tool", None) is original_tool:+ structured_tool = structured+ break+ if structured_tool is None:+ for structured in self.tools or []:+ if sanitize_tool_name(structured.name) == func_name:+ structured_tool = structured+ break++ output_tool = original_tool or structured_tool+from_cache = Falseresult: str = "Tool not found"+ raw_tool_result: Any = resultinput_str = json.dumps(args_dict) if args_dict else ""- if self.tools_handler and self.tools_handler.cache:+ if self.tools_handler and self.tools_handler.cache and output_tool is not None:cached_result = self.tools_handler.cache.read(tool=func_name, input=input_str)if cached_result is not None:- result = (- str(cached_result)- if not isinstance(cached_result, str)- else cached_result- )+ raw_tool_result = cached_result+ result = format_native_tool_output_for_agent(output_tool, cached_result)from_cache = Trueagent_key = getattr(self.agent, "key", "unknown") if self.agent else "unknown"@@ -938,18 +951,6 @@ class CrewAgentExecutor(BaseAgentExecutor):track_delegation_if_needed(func_name, args_dict or {}, self.task)- structured_tool: CrewStructuredTool | None = None- if original_tool is not None:- for structured in self.tools or []:- if getattr(structured, "_original_tool", None) is original_tool:- structured_tool = structured- break- if structured_tool is None:- for structured in self.tools or []:- if sanitize_tool_name(structured.name) == func_name:- structured_tool = structured- break-hook_blocked = Falsebefore_hook_context = ToolCallHookContext(tool_name=func_name,@@ -975,11 +976,18 @@ class CrewAgentExecutor(BaseAgentExecutor):if hook_blocked:result = f"Tool execution blocked by hook. Tool: {func_name}"+ raw_tool_result = resultelif max_usage_reached and original_tool:result = f"Tool '{func_name}' has reached its usage limit of {original_tool.max_usage_count} times and cannot be used anymore."- elif not from_cache and func_name in available_functions:+ raw_tool_result = result+ elif (+ not from_cache+ and func_name in available_functions+ and output_tool is not None+ ):try:raw_result = available_functions[func_name](**(args_dict or {}))+ raw_tool_result = raw_resultif self.tools_handler and self.tools_handler.cache:should_cache = True@@ -996,11 +1004,10 @@ class CrewAgentExecutor(BaseAgentExecutor):tool=func_name, input=input_str, output=raw_result)- result = (- str(raw_result) if not isinstance(raw_result, str) else raw_result- )+ result = format_native_tool_output_for_agent(output_tool, raw_result)except Exception as e:result = f"Error executing tool: {e}"+ raw_tool_result = resultif self.task:self.task.increment_tools_errors()crewai_event_bus.emit(@@ -1024,6 +1031,7 @@ class CrewAgentExecutor(BaseAgentExecutor):task=self.task,crew=self.crew,tool_result=result,+ raw_tool_result=raw_tool_result,)after_hooks = get_after_tool_call_hooks()try:diff --git a/lib/crewai/src/crewai/agents/tools_handler.py b/lib/crewai/src/crewai/agents/tools_handler.pyindex 8ab759b85..c56226bc1 100644--- a/lib/crewai/src/crewai/agents/tools_handler.py+++ b/lib/crewai/src/crewai/agents/tools_handler.py@@ -3,6 +3,7 @@from __future__ import annotationsimport json+from typing import Anyfrom pydantic import BaseModel, Field@@ -25,14 +26,14 @@ class ToolsHandler(BaseModel):def on_tool_use(self,calling: ToolCalling | InstructorToolCalling,- output: str,+ output: Any,should_cache: bool = True,) -> None:"""Run when tool ends running.Args:calling: The tool calling instance.- output: The output from the tool execution.+ output: The raw output from the tool execution.should_cache: Whether to cache the tool output."""self.last_used_tool = callingdiff --git a/lib/crewai/src/crewai/experimental/agent_executor.py b/lib/crewai/src/crewai/experimental/agent_executor.pyindex c026c7509..303330dc6 100644--- a/lib/crewai/src/crewai/experimental/agent_executor.py+++ b/lib/crewai/src/crewai/experimental/agent_executor.py@@ -80,6 +80,7 @@ from crewai.utilities.agent_utils import (enforce_rpm_limit,extract_tool_call_info,format_message_for_llm,+ format_native_tool_output_for_agent,get_llm_response,handle_agent_action_core,handle_context_length,@@ -1905,19 +1906,32 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):):max_usage_reached = True+ structured_tool: CrewStructuredTool | None = None+ if original_tool is not None:+ for structured in self.tools or []:+ if getattr(structured, "_original_tool", None) is original_tool:+ structured_tool = structured+ break+ if structured_tool is None:+ for structured in self.tools or []:+ if sanitize_tool_name(structured.name) == func_name:+ structured_tool = structured+ break++ output_tool = original_tool or structured_tool+# Check cache before executingfrom_cache = False+ result = "Tool not found"+ raw_tool_result: Any = resultinput_str = json.dumps(args_dict) if args_dict else ""- if self.tools_handler and self.tools_handler.cache:+ if self.tools_handler and self.tools_handler.cache and output_tool is not None:cached_result = self.tools_handler.cache.read(tool=func_name, input=input_str)if cached_result is not None:- result = (- str(cached_result)- if not isinstance(cached_result, str)- else cached_result- )+ raw_tool_result = cached_result+ result = format_native_tool_output_for_agent(output_tool, cached_result)from_cache = True# Emit tool usage started event@@ -1936,18 +1950,6 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):track_delegation_if_needed(func_name, args_dict, self.task)- structured_tool: CrewStructuredTool | None = None- if original_tool is not None:- for structured in self.tools or []:- if getattr(structured, "_original_tool", None) is original_tool:- structured_tool = structured- break- if structured_tool is None:- for structured in self.tools or []:- if sanitize_tool_name(structured.name) == func_name:- structured_tool = structured- break-hook_blocked = Falsebefore_hook_context = ToolCallHookContext(tool_name=func_name,@@ -1973,12 +1975,13 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):if hook_blocked:result = f"Tool execution blocked by hook. Tool: {func_name}"- elif not from_cache and not max_usage_reached:- result = "Tool not found"+ raw_tool_result = result+ elif not from_cache and not max_usage_reached and output_tool is not None:if func_name in self._available_functions:try:tool_func = self._available_functions[func_name]raw_result = tool_func(**args_dict)+ raw_tool_result = raw_result# Add to cache after successful execution (before string conversion)if self.tools_handler and self.tools_handler.cache:@@ -1992,14 +1995,12 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):tool=func_name, input=input_str, output=raw_result)- # Convert to string for message- result = (- str(raw_result)- if not isinstance(raw_result, str)- else raw_result+ result = format_native_tool_output_for_agent(+ output_tool, raw_result)except Exception as e:result = f"Error executing tool: {e}"+ raw_tool_result = resultif self.task:self.task.increment_tools_errors()# Emit tool usage error event@@ -2021,6 +2022,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):result = f"Tool '{func_name}' has reached its usage limit of {original_tool.max_usage_count} times and cannot be used anymore."else:result = f"Tool '{func_name}' has reached its maximum usage limit and cannot be used anymore."+ raw_tool_result = result# Execute after_tool_call hooks (even if blocked, to allow logging/monitoring)after_hook_context = ToolCallHookContext(@@ -2031,6 +2033,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):task=self.task,crew=self.crew,tool_result=result,+ raw_tool_result=raw_tool_result,)after_hooks = get_after_tool_call_hooks()try:diff --git a/lib/crewai/src/crewai/hooks/tool_hooks.py b/lib/crewai/src/crewai/hooks/tool_hooks.pyindex b54ca7b10..a860c01d4 100644--- a/lib/crewai/src/crewai/hooks/tool_hooks.py+++ b/lib/crewai/src/crewai/hooks/tool_hooks.py@@ -40,6 +40,8 @@ class ToolCallHookContext:crew: Crew instance (may be None)tool_result: Tool execution result (only set for after_tool_call hooks).Can be modified by returning a new string from after_tool_call hook.+ raw_tool_result: Raw Python tool execution result (only set for+ after_tool_call hooks). This is not modified by after hooks."""def __init__(@@ -51,6 +53,7 @@ class ToolCallHookContext:task: Task | None = None,crew: Crew | None = None,tool_result: str | None = None,+ raw_tool_result: Any | None = None,) -> None:"""Initialize tool call hook context.@@ -62,6 +65,7 @@ class ToolCallHookContext:task: Optional current taskcrew: Optional crew instancetool_result: Optional tool result (for after hooks)+ raw_tool_result: Optional raw tool result (for after hooks)"""self.tool_name = tool_nameself.tool_input = tool_input@@ -70,6 +74,7 @@ class ToolCallHookContext:self.task = taskself.crew = crewself.tool_result = tool_result+ self.raw_tool_result = raw_tool_resultdef request_human_input(self,diff --git a/lib/crewai/src/crewai/tools/base_tool.py b/lib/crewai/src/crewai/tools/base_tool.pyindex 31c5009bd..c6c3dba15 100644--- a/lib/crewai/src/crewai/tools/base_tool.py+++ b/lib/crewai/src/crewai/tools/base_tool.py@@ -33,6 +33,8 @@ from typing_extensions import TypeIsfrom crewai.tools.structured_tool import (CrewStructuredTool,_deserialize_schema,+ _format_tool_output_for_agent,+ _infer_result_schema_from_callable,_serialize_schema,build_schema_hint,)@@ -149,6 +151,11 @@ class BaseTool(BaseModel, ABC):validate_default=True,description="The schema for the arguments that the tool accepts.",)+ result_schema: type[PydanticBaseModel] | None = Field(+ default=None,+ validate_default=True,+ description="The schema for the output that the tool returns.",+ )@field_serializer("args_schema", when_used="json")def _serialize_args_schema(@@ -156,6 +163,12 @@ class BaseTool(BaseModel, ABC):) -> dict[str, Any] | None:return _serialize_schema(schema)+ @field_serializer("result_schema", when_used="json")+ def _serialize_result_schema(+ self, schema: type[PydanticBaseModel] | None+ ) -> dict[str, Any] | None:+ return _serialize_schema(schema)+description_updated: bool = Field(default=False, description="Flag to check if the description has been updated.")@@ -233,6 +246,17 @@ class BaseTool(BaseModel, ABC):return create_model(f"{cls.__name__}Schema", **fields)+ @field_validator("result_schema", mode="before")+ @classmethod+ def _default_result_schema(+ cls, v: type[PydanticBaseModel] | dict[str, Any] | None+ ) -> type[PydanticBaseModel] | None:+ if isinstance(v, dict):+ return _deserialize_schema(v)+ if v is not None:+ return v+ return _infer_result_schema_from_callable(cls._run)+@field_validator("max_usage_count", mode="before")@classmethoddef validate_max_usage_count(cls, v: int | None) -> int | None:@@ -340,6 +364,10 @@ class BaseTool(BaseModel, ABC):"Override _arun for async support or use run() for sync execution.")+ def format_output_for_agent(self, raw_result: Any) -> str:+ """Format a raw tool result into the string representation sent to an agent."""+ return _format_tool_output_for_agent(self, raw_result)+def reset_usage_count(self) -> None:"""Reset the current usage count to zero."""self.current_usage_count = 0@@ -369,6 +397,7 @@ class BaseTool(BaseModel, ABC):name=self.name,description=self.description,args_schema=self.args_schema,+ result_schema=self.result_schema,func=self._run,result_as_answer=self.result_as_answer,max_usage_count=self.max_usage_count,@@ -390,6 +419,9 @@ class BaseTool(BaseModel, ABC):raise ValueError("The provided tool must have a callable 'func' attribute.")args_schema = getattr(tool, "args_schema", None)+ result_schema = getattr(tool, "result_schema", None)+ if result_schema is None:+ result_schema = _infer_result_schema_from_callable(tool.func)if args_schema is None:func_signature = signature(tool.func)@@ -420,6 +452,7 @@ class BaseTool(BaseModel, ABC):description=getattr(tool, "description", ""),func=tool.func,args_schema=args_schema,+ result_schema=result_schema,)def _set_args_schema(self) -> None:@@ -568,6 +601,9 @@ class Tool(BaseTool, Generic[P, R]):raise ValueError("The provided tool must have a callable 'func' attribute.")args_schema = getattr(tool, "args_schema", None)+ result_schema = getattr(tool, "result_schema", None)+ if result_schema is None:+ result_schema = _infer_result_schema_from_callable(tool.func)if args_schema is None:func_signature = signature(tool.func)@@ -598,6 +634,7 @@ class Tool(BaseTool, Generic[P, R]):description=getattr(tool, "description", ""),func=tool.func,args_schema=args_schema,+ result_schema=result_schema,)@@ -621,6 +658,7 @@ def tool(name: str,/,*,+ result_schema: type[BaseModel] | None = ...,result_as_answer: bool = ...,max_usage_count: int | None = ...,) -> Callable[[Callable[P2, R2]], Tool[P2, R2]]: ...@@ -629,6 +667,7 @@ def tool(@overloaddef tool(*,+ result_schema: type[BaseModel] | None = ...,result_as_answer: bool = ...,max_usage_count: int | None = ...,) -> Callable[[Callable[P2, R2]], Tool[P2, R2]]: ...@@ -636,6 +675,7 @@ def tool(def tool(*args: Callable[P2, R2] | str,+ result_schema: type[BaseModel] | None = None,result_as_answer: bool = False,max_usage_count: int | None = None,) -> Tool[P2, R2] | Callable[[Callable[P2, R2]], Tool[P2, R2]]:@@ -649,6 +689,7 @@ def tool(Args:*args: Either the function to decorate or a custom tool name.result_as_answer: If True, the tool result becomes the final agent answer.+ result_schema: Optional schema for the output that the tool returns.max_usage_count: Maximum times this tool can be used. None means unlimited.Returns:@@ -690,12 +731,16 @@ def tool(class_name = "".join(tool_name.split()).title()args_schema = create_model(class_name, **fields)+ resolved_result_schema = (+ result_schema or _infer_result_schema_from_callable(f)+ )return Tool(name=tool_name,description=f.__doc__,func=f,args_schema=args_schema,+ result_schema=resolved_result_schema,result_as_answer=result_as_answer,max_usage_count=max_usage_count,current_usage_count=0,diff --git a/lib/crewai/src/crewai/tools/structured_tool.py b/lib/crewai/src/crewai/tools/structured_tool.pyindex 6c24f52dc..8ecba8549 100644--- a/lib/crewai/src/crewai/tools/structured_tool.py+++ b/lib/crewai/src/crewai/tools/structured_tool.py@@ -5,7 +5,8 @@ from collections.abc import Callableimport inspectimport jsonimport textwrap-from typing import TYPE_CHECKING, Annotated, Any, get_type_hints+from typing import TYPE_CHECKING, Annotated, Any, cast, get_type_hints+import warningsfrom pydantic import (BaseModel,@@ -36,6 +37,52 @@ def _deserialize_schema(v: Any) -> type[BaseModel] | None:return None+def _infer_result_schema_from_callable(+ func: Callable[..., Any],+) -> type[BaseModel] | None:+ try:+ return_annotation = get_type_hints(func).get("return", inspect.Signature.empty)+ except Exception:+ return_annotation = inspect.signature(func).return_annotation++ if isinstance(return_annotation, type) and issubclass(return_annotation, BaseModel):+ return return_annotation++ return None+++def _format_tool_output_for_agent(tool: Any, raw_result: Any) -> str:+ original_tool = getattr(tool, "_original_tool", None)+ if original_tool is not None:+ return cast(str, original_tool.format_output_for_agent(raw_result))++ result_schema = getattr(tool, "result_schema", None)+ if not (isinstance(result_schema, type) and issubclass(result_schema, BaseModel)):+ return str(raw_result)++ try:+ validation_input = raw_result+ if isinstance(raw_result, BaseModel) and not isinstance(+ raw_result, result_schema+ ):+ validation_input = raw_result.model_dump()++ validated = result_schema.model_validate(validation_input)+ return validated.model_dump_json()+ except Exception as exc:+ warnings.warn(+ (+ f"Failed to validate or serialize output from tool "+ f"'{getattr(tool, 'name', '<unknown>')}' using result_schema "+ f"'{result_schema.__name__}': {exc.__class__.__name__}. "+ "Falling back to str(raw_result)."+ ),+ RuntimeWarning,+ stacklevel=2,+ )+ return str(raw_result)++if TYPE_CHECKING:pass@@ -81,6 +128,11 @@ class CrewStructuredTool(BaseModel):BeforeValidator(_deserialize_schema),PlainSerializer(_serialize_schema),] = Field(default=None)+ result_schema: Annotated[+ type[BaseModel] | None,+ BeforeValidator(_deserialize_schema),+ PlainSerializer(_serialize_schema),+ ] = Field(default=None)func: Any = Field(default=None, exclude=True)result_as_answer: bool = Field(default=False)max_usage_count: int | None = Field(default=None)@@ -103,6 +155,7 @@ class CrewStructuredTool(BaseModel):description: str | None = None,return_direct: bool = False,args_schema: type[BaseModel] | None = None,+ result_schema: type[BaseModel] | None = None,infer_schema: bool = True,**kwargs: Any,) -> CrewStructuredTool:@@ -114,6 +167,7 @@ class CrewStructuredTool(BaseModel):description: The description of the tool. Defaults to the function docstringreturn_direct: Whether to return the output directlyargs_schema: Optional schema for the function arguments+ result_schema: Optional schema for the function outputinfer_schema: Whether to infer the schema from the function signature**kwargs: Additional arguments to pass to the tool@@ -149,10 +203,16 @@ class CrewStructuredTool(BaseModel):name=name,description=description,args_schema=schema,+ result_schema=result_schema or _infer_result_schema_from_callable(func),func=func,result_as_answer=return_direct,+ **kwargs,)+ def format_output_for_agent(self, raw_result: Any) -> str:+ """Format a raw tool result into the string representation sent to an agent."""+ return _format_tool_output_for_agent(self, raw_result)+@staticmethoddef _create_schema_from_function(name: str,diff --git a/lib/crewai/src/crewai/tools/tool_usage.py b/lib/crewai/src/crewai/tools/tool_usage.pyindex b34921839..e92ba03ee 100644--- a/lib/crewai/src/crewai/tools/tool_usage.py+++ b/lib/crewai/src/crewai/tools/tool_usage.py@@ -62,6 +62,9 @@ OPENAI_BIGGER_MODELS: list[]+_RAW_RESULT_UNSET = object()++class ToolUsageError(Exception):"""Exception raised for errors in the tool usage."""@@ -106,6 +109,7 @@ class ToolUsage:self.action = actionself.function_calling_llm = function_calling_llmself.fingerprint_context = fingerprint_context or {}+ self.last_raw_result: Any = _RAW_RESULT_UNSETif (self.function_calling_llm@@ -120,6 +124,11 @@ class ToolUsage:"""Parse the tool string and return the tool calling."""return self._tool_calling(tool_string)+ def get_last_raw_result(self, fallback: Any) -> Any:+ if self.last_raw_result is _RAW_RESULT_UNSET:+ return fallback+ return self.last_raw_result+def use(self, calling: ToolCalling | InstructorToolCalling, tool_string: str) -> str:@@ -231,6 +240,7 @@ class ToolUsage:result = I18N_DEFAULT.errors("task_repeated_usage").format(tool_names=self.tools_names)+ self.last_raw_result = resultself._telemetry.tool_repeated_usage(llm=self.function_calling_llm,tool_name=sanitize_tool_name(tool.name),@@ -298,6 +308,7 @@ class ToolUsage:)if usage_limit_error:result = usage_limit_error+ self.last_raw_result = resultself._telemetry.tool_usage_error(llm=self.function_calling_llm)result = self._format_result(result=result)elif result is None:@@ -359,7 +370,10 @@ class ToolUsage:tool_name=sanitize_tool_name(tool.name),attempts=self._run_attempts,)- result = self._format_result(result=result)+ self.last_raw_result = result+ result = self._format_result(+ result=tool.format_output_for_agent(result)+ )data = {"result": result,"tool_name": sanitize_tool_name(tool.name),@@ -421,6 +435,7 @@ class ToolUsage:result = ToolUsageError(f"\n{error_message}.\nMoving on then. {I18N_DEFAULT.slice('format').format(tool_names=self.tools_names)}").message+ self.last_raw_result = resultif self.task:self.task.increment_tools_errors()if self.agent and self.agent.verbose:@@ -430,7 +445,10 @@ class ToolUsage:self.task.increment_tools_errors()should_retry = Trueelse:- result = self._format_result(result=result)+ self.last_raw_result = result+ result = self._format_result(+ result=tool.format_output_for_agent(result)+ )finally:if started_event_emitted and not error_event_emitted:@@ -460,6 +478,7 @@ class ToolUsage:result = I18N_DEFAULT.errors("task_repeated_usage").format(tool_names=self.tools_names)+ self.last_raw_result = resultself._telemetry.tool_repeated_usage(llm=self.function_calling_llm,tool_name=sanitize_tool_name(tool.name),@@ -529,6 +548,7 @@ class ToolUsage:)if usage_limit_error:result = usage_limit_error+ self.last_raw_result = resultself._telemetry.tool_usage_error(llm=self.function_calling_llm)result = self._format_result(result=result)elif result is None:@@ -590,7 +610,10 @@ class ToolUsage:tool_name=sanitize_tool_name(tool.name),attempts=self._run_attempts,)- result = self._format_result(result=result)+ self.last_raw_result = result+ result = self._format_result(+ result=tool.format_output_for_agent(result)+ )data = {"result": result,"tool_name": sanitize_tool_name(tool.name),@@ -652,6 +675,7 @@ class ToolUsage:result = ToolUsageError(f"\n{error_message}.\nMoving on then. {I18N_DEFAULT.slice('format').format(tool_names=self.tools_names)}").message+ self.last_raw_result = resultif self.task:self.task.increment_tools_errors()if self.agent and self.agent.verbose:@@ -661,7 +685,10 @@ class ToolUsage:self.task.increment_tools_errors()should_retry = Trueelse:- result = self._format_result(result=result)+ self.last_raw_result = result+ result = self._format_result(+ result=tool.format_output_for_agent(result)+ )finally:if started_event_emitted and not error_event_emitted:diff --git a/lib/crewai/src/crewai/utilities/agent_utils.py b/lib/crewai/src/crewai/utilities/agent_utils.pyindex 80f8ab242..e933a38a8 100644--- a/lib/crewai/src/crewai/utilities/agent_utils.py+++ b/lib/crewai/src/crewai/utilities/agent_utils.py@@ -1383,6 +1383,19 @@ class NativeToolCallResult:tool_message: LLMMessage = field(default_factory=dict) # type: ignore[assignment]+def format_native_tool_output_for_agent(tool: Any, raw_result: Any) -> str:+ """Format native tool output when a tool explicitly defines a formatter."""+ formatter = inspect.getattr_static(tool, "format_output_for_agent", None)+ if formatter is None:+ return str(raw_result)++ runtime_formatter = getattr(tool, "format_output_for_agent", None)+ if not callable(runtime_formatter):+ return str(raw_result)++ return str(runtime_formatter(raw_result))++def execute_single_native_tool_call(tool_call: Any,*,@@ -1456,18 +1469,24 @@ def execute_single_native_tool_call(original_tool = toolbreak+ structured_tool: CrewStructuredTool | None = None+ for structured in structured_tools or []:+ if sanitize_tool_name(structured.name) == func_name:+ structured_tool = structured+ break++ output_tool = original_tool or structured_tool+from_cache = Falseinput_str = json.dumps(args_dict) if args_dict else ""result = "Tool not found"+ raw_tool_result: Any = result- if tools_handler and tools_handler.cache:+ if tools_handler and tools_handler.cache and output_tool is not None:cached_result = tools_handler.cache.read(tool=func_name, input=input_str)if cached_result is not None:- result = (- str(cached_result)- if not isinstance(cached_result, str)- else cached_result- )+ raw_tool_result = cached_result+ result = format_native_tool_output_for_agent(output_tool, cached_result)from_cache = Truestarted_at = datetime.now()@@ -1486,12 +1505,6 @@ def execute_single_native_tool_call(track_delegation_if_needed(func_name, args_dict, task)- structured_tool: CrewStructuredTool | None = None- for structured in structured_tools or []:- if sanitize_tool_name(structured.name) == func_name:- structured_tool = structured- break-hook_blocked = Falsebefore_hook_context = ToolCallHookContext(tool_name=func_name,@@ -1512,11 +1525,13 @@ def execute_single_native_tool_call(error_event_emitted = Falseif hook_blocked:result = f"Tool execution blocked by hook. Tool: {func_name}"+ raw_tool_result = resultelif not from_cache:- if func_name in available_functions:+ if func_name in available_functions and output_tool is not None:try:tool_func = available_functions[func_name]raw_result = tool_func(**args_dict)+ raw_tool_result = raw_resultif tools_handler and tools_handler.cache:should_cache = True@@ -1529,11 +1544,10 @@ def execute_single_native_tool_call(tool=func_name, input=input_str, output=raw_result)- result = (- str(raw_result) if not isinstance(raw_result, str) else raw_result- )+ result = format_native_tool_output_for_agent(output_tool, raw_result)except Exception as e:result = f"Error executing tool: {e}"+ raw_tool_result = resultif task:task.increment_tools_errors()crewai_event_bus.emit(@@ -1559,6 +1573,7 @@ def execute_single_native_tool_call(task=task,crew=crew,tool_result=result,+ raw_tool_result=raw_tool_result,)try:for after_hook in get_after_tool_call_hooks():diff --git a/lib/crewai/src/crewai/utilities/tool_utils.py b/lib/crewai/src/crewai/utilities/tool_utils.pyindex e19c3c81a..dcb25594c 100644--- a/lib/crewai/src/crewai/utilities/tool_utils.py+++ b/lib/crewai/src/crewai/utilities/tool_utils.py@@ -116,6 +116,7 @@ async def aexecute_tool_and_check_finality(logger.log("error", f"Error in before_tool_call hook: {e}")tool_result = await tool_usage.ause(tool_calling, agent_action.text)+ raw_tool_result = tool_usage.get_last_raw_result(tool_result)after_hook_context = ToolCallHookContext(tool_name=sanitized_tool_name,@@ -125,6 +126,7 @@ async def aexecute_tool_and_check_finality(task=task,crew=crew,tool_result=tool_result,+ raw_tool_result=raw_tool_result,)after_hooks = get_after_tool_call_hooks()@@ -234,6 +236,7 @@ def execute_tool_and_check_finality(logger.log("error", f"Error in before_tool_call hook: {e}")tool_result = tool_usage.use(tool_calling, agent_action.text)+ raw_tool_result = tool_usage.get_last_raw_result(tool_result)after_hook_context = ToolCallHookContext(tool_name=sanitized_tool_name,@@ -243,6 +246,7 @@ def execute_tool_and_check_finality(task=task,crew=crew,tool_result=tool_result,+ raw_tool_result=raw_tool_result,)after_hooks = get_after_tool_call_hooks()diff --git a/lib/crewai/tests/agents/test_native_tool_calling.py b/lib/crewai/tests/agents/test_native_tool_calling.pyindex b7e0df199..894c0bd45 100644--- a/lib/crewai/tests/agents/test_native_tool_calling.py+++ b/lib/crewai/tests/agents/test_native_tool_calling.py@@ -7,6 +7,7 @@ when the LLM supports it, across multiple providers.from __future__ import annotationsfrom collections.abc import Generator+import jsonimport osimport threadingimport time@@ -20,7 +21,7 @@ from crewai import Agent, Crew, Taskfrom crewai.agents.parser import AgentFinishfrom crewai.events import crewai_event_busfrom crewai.hooks import register_after_tool_call_hook, register_before_tool_call_hook-from crewai.hooks.tool_hooks import ToolCallHookContext+from crewai.hooks.tool_hooks import ToolCallHookContext, clear_after_tool_call_hooksfrom crewai.llm import LLMfrom crewai.tools.base_tool import BaseTool@@ -1197,6 +1198,76 @@ class TestNativeToolCallingJsonParseError:assert result["result"] == "ran: print(1)"+ def test_typed_output_is_json_agent_text(self) -> None:+ class SearchOutput(BaseModel):+ query: str+ score: float++ class TypedSearchTool(BaseTool):+ name: str = "typed_search"+ description: str = "Search for information"+ result_schema: type[BaseModel] = SearchOutput++ def _run(self, query: str) -> SearchOutput:+ return SearchOutput(query=query, score=0.8)++ tool = TypedSearchTool()+ 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_typed",+ func_name="typed_search",+ func_args='{"query": "crew"}',+ available_functions=available_functions,+ )++ assert json.loads(result["result"]) == {"query": "crew", "score": 0.8}++ def test_typed_output_after_hook_includes_raw_tool_result(self) -> None:+ from crewai.utilities.agent_utils import convert_tools_to_openai_schema++ class SearchOutput(BaseModel):+ query: str+ score: float++ class TypedSearchTool(BaseTool):+ name: str = "typed_search"+ description: str = "Search for information"+ result_schema: type[BaseModel] = SearchOutput++ def _run(self, query: str) -> SearchOutput:+ return SearchOutput(query=query, score=0.8)++ seen_results: list[tuple[str | None, object]] = []++ def after_hook(context: ToolCallHookContext) -> None:+ seen_results.append((context.tool_result, context.raw_tool_result))++ tool = TypedSearchTool()+ executor = self._make_executor([tool])+ _, available_functions, _ = convert_tools_to_openai_schema([tool])++ clear_after_tool_call_hooks()+ register_after_tool_call_hook(after_hook)+ try:+ result = executor._execute_single_native_tool_call(+ call_id="call_typed",+ func_name="typed_search",+ func_args='{"query": "crew"}',+ available_functions=available_functions,+ )+ finally:+ clear_after_tool_call_hooks()++ assert json.loads(result["result"]) == {"query": "crew", "score": 0.8}+ assert seen_results == [+ ('{"query":"crew","score":0.8}', SearchOutput(query="crew", score=0.8))+ ]+def test_native_tool_loop_falls_back_when_provider_rejects_tools(self) -> None:"""Unsupported native tools errors should continue through ReAct."""diff --git a/lib/crewai/tests/hooks/test_tool_hooks.py b/lib/crewai/tests/hooks/test_tool_hooks.pyindex 347eb56e5..14c6848a8 100644--- a/lib/crewai/tests/hooks/test_tool_hooks.py+++ b/lib/crewai/tests/hooks/test_tool_hooks.py@@ -91,20 +91,24 @@ class TestToolCallHookContext:assert context.task == mock_taskassert context.crew == mock_crewassert context.tool_result is None+ assert context.raw_tool_result is Nonedef test_context_with_result(self, mock_tool):"""Test that context includes result when provided."""tool_input = {"arg1": "value1"}tool_result = "Test tool result"+ raw_tool_result = {"value": 42}context = ToolCallHookContext(tool_name="test_tool",tool_input=tool_input,tool=mock_tool,tool_result=tool_result,+ raw_tool_result=raw_tool_result,)assert context.tool_result == tool_result+ assert context.raw_tool_result == raw_tool_resultdef test_tool_input_is_mutable_reference(self, mock_tool):"""Test that modifying context.tool_input modifies the original dict."""diff --git a/lib/crewai/tests/tools/test_base_tool.py b/lib/crewai/tests/tools/test_base_tool.pyindex 7648ad73b..52661fffc 100644--- a/lib/crewai/tests/tools/test_base_tool.py+++ b/lib/crewai/tests/tools/test_base_tool.py@@ -1,12 +1,13 @@import asynciofrom collections.abc import Callable+import jsonfrom unittest.mock import patchfrom crewai.agent import Agentfrom crewai.crew import Crewfrom crewai.task import Taskfrom crewai.tools import BaseTool, tool-from pydantic import BaseModel, Field+from pydantic import BaseModel, Field, RootModelimport pytest@@ -351,6 +352,262 @@ class TestToolDecoratorRunValidation:assert result == "Hello, World!"+class SearchOutput(BaseModel):+ query: str+ score: float+++class SearchResults(RootModel[list[SearchOutput]]):+ pass+++class ExplicitSearchTool(BaseTool):+ name: str = "search"+ description: str = "Search for a query"+ result_schema: type[BaseModel] = SearchOutput++ def _run(self, query: str) -> dict[str, object]:+ return {"query": query, "score": 0.8}+++class InferredSearchTool(BaseTool):+ name: str = "search"+ description: str = "Search for a query"++ def _run(self, query: str) -> SearchOutput:+ return SearchOutput(query=query, score=0.7)+++class RootSearchTool(BaseTool):+ name: str = "search"+ description: str = "Search for a query"++ def _run(self, query: str) -> SearchResults:+ return SearchResults([SearchOutput(query=query, score=1.0)])+++class DictAnnotatedSearchTool(BaseTool):+ name: str = "search"+ description: str = "Search for a query"++ def _run(self, query: str) -> dict[str, object]:+ return {"query": query, "score": 0.5}+++def _make_explicit_decorator_tool() -> BaseTool:+ @tool("search", result_schema=SearchOutput)+ def search(query: str) -> dict[str, object]:+ """Search for a query."""+ return {"query": query, "score": 0.8}++ return search+++def _make_inferred_decorator_tool() -> BaseTool:+ @tool("search")+ def search(query: str) -> SearchOutput:+ """Search for a query."""+ return SearchOutput(query=query, score=0.6)++ return search+++def _make_root_decorator_tool() -> BaseTool:+ @tool("search")+ def search(query: str) -> SearchResults:+ """Search for a query."""+ return SearchResults([SearchOutput(query=query, score=1.0)])++ return search+++class TestToolOutputSchema:+ @pytest.mark.parametrize(+ ("tool_cls", "expected_raw", "expected_agent_payload"),+ [+ pytest.param(+ ExplicitSearchTool,+ {"query": "crew", "score": 0.8},+ {"query": "crew", "score": 0.8},+ id="explicit-schema",+ ),+ pytest.param(+ InferredSearchTool,+ SearchOutput(query="crew", score=0.7),+ {"query": "crew", "score": 0.7},+ id="inferred-base-model",+ ),+ pytest.param(+ RootSearchTool,+ SearchResults([SearchOutput(query="crew", score=1.0)]),+ [{"query": "crew", "score": 1.0}],+ id="inferred-root-model",+ ),+ ],+ )+ def test_base_tools_return_raw_result_and_json_agent_text(+ self,+ tool_cls: type[BaseTool],+ expected_raw: object,+ expected_agent_payload: object,+ ) -> None:+ t = tool_cls()++ raw_result = t.run(query="crew")++ assert raw_result == expected_raw+ assert json.loads(t.format_output_for_agent(raw_result)) == (+ expected_agent_payload+ )++ def test_base_tool_does_not_infer_non_pydantic_return_annotation(self) -> None:+ t = DictAnnotatedSearchTool()++ raw_result = t.run(query="crew")++ assert raw_result == {"query": "crew", "score": 0.5}+ assert t.format_output_for_agent(raw_result) == str(raw_result)++ @pytest.mark.parametrize(+ ("make_tool", "expected_raw", "expected_agent_payload"),+ [+ pytest.param(+ _make_explicit_decorator_tool,+ {"query": "crew", "score": 0.8},+ {"query": "crew", "score": 0.8},+ id="explicit-schema",+ ),+ pytest.param(+ _make_inferred_decorator_tool,+ SearchOutput(query="crew", score=0.6),+ {"query": "crew", "score": 0.6},+ id="inferred-base-model",+ ),+ pytest.param(+ _make_root_decorator_tool,+ SearchResults([SearchOutput(query="crew", score=1.0)]),+ [{"query": "crew", "score": 1.0}],+ id="inferred-root-model",+ ),+ ],+ )+ def test_decorator_tools_return_raw_result_and_json_agent_text(+ self,+ make_tool: Callable[[], BaseTool],+ expected_raw: object,+ expected_agent_payload: object,+ ) -> None:+ search = make_tool()++ raw_result = search.run(query="crew")++ assert raw_result == expected_raw+ assert json.loads(search.format_output_for_agent(raw_result)) == (+ expected_agent_payload+ )++ def test_decorator_tool_does_not_infer_non_pydantic_return_annotation(+ self,+ ) -> None:+ @tool("search")+ def search(query: str) -> dict[str, object]:+ """Search for a query."""+ return {"query": query, "score": 0.5}++ raw_result = search.run(query="crew")++ assert raw_result == {"query": "crew", "score": 0.5}+ assert search.format_output_for_agent(raw_result) == str(raw_result)++ def test_explicit_result_schema_wins_over_return_annotation(self) -> None:+ class AlternateOutput(BaseModel):+ value: str++ @tool("search", result_schema=AlternateOutput)+ def search(query: str) -> SearchOutput:+ """Search for a query."""+ return SearchOutput(query=query, score=0.6)++ raw_result = search.run(query="crew")++ with pytest.warns(RuntimeWarning, match="AlternateOutput"):+ agent_text = search.format_output_for_agent(raw_result)++ assert raw_result == SearchOutput(query="crew", score=0.6)+ assert agent_text == str(raw_result)++ def test_invalid_typed_output_warns_and_uses_string_agent_text(+ self,+ ) -> None:+ @tool("search", result_schema=SearchOutput)+ def search(query: str) -> dict[str, object]:+ """Search for a query."""+ return {"query": query, "score": "not-a-float"}++ raw_result = search.run(query="crew")++ with pytest.warns(RuntimeWarning, match="Failed to validate or serialize"):+ agent_text = search.format_output_for_agent(raw_result)++ assert raw_result == {"query": "crew", "score": "not-a-float"}+ assert agent_text == str(raw_result)++ def test_unserializable_typed_output_warns_and_uses_string_agent_text(+ self,+ ) -> None:+ class OpaqueOutput(BaseModel):+ value: object++ raw_result = OpaqueOutput(value=object())++ @tool("opaque", result_schema=OpaqueOutput)+ def opaque() -> OpaqueOutput:+ """Return an opaque object."""+ return raw_result++ result = opaque.run()++ with pytest.warns(RuntimeWarning, match="Failed to validate or serialize"):+ agent_text = opaque.format_output_for_agent(result)++ assert result is raw_result+ assert agent_text == str(raw_result)++ def test_result_schema_behavior_carries_over_to_structured_tool(self) -> None:+ structured = ExplicitSearchTool().to_structured_tool()++ raw_result = structured.invoke({"query": "crew"})++ assert raw_result == {"query": "crew", "score": 0.8}+ assert json.loads(structured.format_output_for_agent(raw_result)) == {+ "query": "crew",+ "score": 0.8,+ }++ def test_custom_agent_output_formatter_carries_over_to_structured_tool(+ self,+ ) -> None:+ class MarkdownSearchTool(BaseTool):+ name: str = "markdown_search"+ description: str = "Search for information"+ result_schema: type[BaseModel] = SearchOutput++ def _run(self, query: str) -> SearchOutput:+ return SearchOutput(query=query, score=0.8)++ def format_output_for_agent(self, raw_result: object) -> str:+ result = self.result_schema.model_validate(raw_result)+ return f"### Search result\n\n- Query: `{result.query}`\n- Score: {result.score}"++ structured = MarkdownSearchTool().to_structured_tool()++ raw_result = structured.invoke({"query": "crew"})++ assert raw_result == SearchOutput(query="crew", score=0.8)+ assert structured.format_output_for_agent(raw_result) == (+ "### Search result\n\n- Query: `crew`\n- Score: 0.8"+ )+# Async arun() Schema Validation Testsdiff --git a/lib/crewai/tests/tools/test_structured_tool.py b/lib/crewai/tests/tools/test_structured_tool.pyindex 27c463d47..0241abbcf 100644--- a/lib/crewai/tests/tools/test_structured_tool.py+++ b/lib/crewai/tests/tools/test_structured_tool.py@@ -1,5 +1,7 @@+import json+from crewai.tools.structured_tool import CrewStructuredTool-from pydantic import BaseModel, Field+from pydantic import BaseModel, Field, RootModelimport pytest@@ -86,6 +88,118 @@ def test_from_function(basic_function):assert isinstance(tool.args_schema, type(BaseModel))+class StructuredOutput(BaseModel):+ value: str+ count: int+++class StructuredOutputList(RootModel[list[StructuredOutput]]):+ pass+++def _build_explicit_structured_value(value: str) -> dict[str, object]:+ """Build a value."""+ return {"value": value, "count": 1}+++def _build_inferred_structured_value(value: str) -> StructuredOutput:+ """Build a value."""+ return StructuredOutput(value=value, count=1)+++def _build_structured_values(value: str) -> StructuredOutputList:+ """Build values."""+ return StructuredOutputList([StructuredOutput(value=value, count=1)])+++def _build_plain_structured_value(value: str) -> dict[str, object]:+ """Build a value."""+ return {"value": value, "count": 1}+++ ("func", "result_schema", "expected_raw", "expected_agent_payload"),+ [+ pytest.param(+ _build_explicit_structured_value,+ StructuredOutput,+ {"value": "crew", "count": 1},+ {"value": "crew", "count": 1},+ id="explicit-schema",+ ),+ pytest.param(+ _build_inferred_structured_value,+ None,+ StructuredOutput(value="crew", count=1),+ {"value": "crew", "count": 1},+ id="inferred-base-model",+ ),+ pytest.param(+ _build_structured_values,+ None,+ StructuredOutputList([StructuredOutput(value="crew", count=1)]),+ [{"value": "crew", "count": 1}],+ id="inferred-root-model",+ ),+ ],+)+def test_from_function_returns_raw_result_and_json_agent_text(+ func,+ result_schema,+ expected_raw,+ expected_agent_payload,+):+ kwargs = {"result_schema": result_schema} if result_schema is not None else {}+ tool = CrewStructuredTool.from_function(+ func=func,+ name="build_value",+ **kwargs,+ )++ raw_result = tool.invoke({"value": "crew"})++ assert raw_result == expected_raw+ assert json.loads(tool.format_output_for_agent(raw_result)) == (+ expected_agent_payload+ )+++def test_from_function_does_not_infer_non_pydantic_result_schema():+ tool = CrewStructuredTool.from_function(+ func=_build_plain_structured_value,+ name="build_value",+ )++ raw_result = tool.invoke({"value": "crew"})++ assert raw_result == {"value": "crew", "count": 1}+ assert tool.format_output_for_agent(raw_result) == str(raw_result)+++def test_invalid_typed_output_warns_and_uses_string_agent_text():+ def build_value(value: str) -> dict[str, object]:+ """Build a value."""+ return {"value": value, "count": "wrong"}++ tool = CrewStructuredTool.from_function(+ func=build_value,+ name="build_value",+ result_schema=StructuredOutput,+ )+ raw_result = tool.invoke({"value": "crew"})++ with pytest.warns(+ RuntimeWarning, match="Failed to validate or serialize"+ ) as warnings:+ agent_text = tool.format_output_for_agent(raw_result)++ assert raw_result == {"value": "crew", "count": "wrong"}+ assert agent_text == str(raw_result)+ warning_message = str(warnings[0].message)+ assert "ValidationError" in warning_message+ assert "wrong" not in warning_message++def test_validate_function_signature(basic_function, schema_class):"""Test function signature validation"""tool = CrewStructuredTool(diff --git a/lib/crewai/tests/tools/test_tool_usage.py b/lib/crewai/tests/tools/test_tool_usage.pyindex ba4fe72dd..9d61c93a9 100644--- a/lib/crewai/tests/tools/test_tool_usage.py+++ b/lib/crewai/tests/tools/test_tool_usage.py@@ -1,4 +1,5 @@import datetime+from collections.abc import Callableimport jsonimport randomimport threading@@ -6,6 +7,9 @@ import timefrom unittest.mock import MagicMock, patchfrom crewai import Agent, Task+from crewai.agents.cache.cache_handler import CacheHandler+from crewai.agents.parser import AgentAction+from crewai.agents.tools_handler import ToolsHandlerfrom crewai.events.event_bus import crewai_event_busfrom crewai.events.types.tool_usage_events import (ToolSelectionErrorEvent,@@ -14,8 +18,15 @@ from crewai.events.types.tool_usage_events import (ToolUsageStartedEvent,ToolValidateInputErrorEvent,)+from crewai.hooks.tool_hooks import (+ ToolCallHookContext,+ clear_after_tool_call_hooks,+ register_after_tool_call_hook,+)from crewai.tools import BaseTool+from crewai.tools.tool_calling import ToolCallingfrom crewai.tools.tool_usage import ToolUsage+from crewai.utilities.tool_utils import execute_tool_and_check_finalityfrom pydantic import BaseModel, Fieldimport pytest@@ -38,6 +49,19 @@ class RandomNumberTool(BaseTool):return random.randint(min_value, max_value) # noqa: S311+class SearchOutput(BaseModel):+ query: str+ score: float+++class TypedSearchTool(BaseTool):+ name: str = "typed_search"+ description: str = "Search for a query"++ def _run(self, query: str) -> SearchOutput:+ return SearchOutput(query=query, score=0.7)++# Example agent and taskexample_agent = Agent(role="Number Generator",@@ -117,6 +141,126 @@ def test_tool_usage_render():assert '"description": "The maximum value of the range (inclusive)"' in rendered+def test_tool_usage_returns_json_agent_text_for_typed_output():+ tool = TypedSearchTool().to_structured_tool()+ tool_usage = ToolUsage(+ tools_handler=None,+ tools=[tool],+ task=None,+ function_calling_llm=MagicMock(),+ agent=None,+ action=MagicMock(),+ )++ result = tool_usage.use(+ calling=ToolCalling(+ tool_name="typed_search",+ arguments={"query": "crew"},+ ),+ tool_string='Action: typed_search\nAction Input: {"query": "crew"}',+ )++ assert json.loads(result) == {"query": "crew", "score": 0.7}+++def test_tool_usage_cache_callback_receives_raw_typed_output():+ raw_results: list[object] = []++ def cache_result(_args: object, result: object) -> bool:+ raw_results.append(result)+ return True++ class CacheAwareTypedSearchTool(TypedSearchTool):+ cache_function: Callable = cache_result++ tools_handler = MagicMock()+ tools_handler.cache = None+ tools_handler.last_used_tool = None+ tool = CacheAwareTypedSearchTool().to_structured_tool()+ tool_usage = ToolUsage(+ tools_handler=tools_handler,+ tools=[tool],+ task=None,+ function_calling_llm=MagicMock(),+ agent=None,+ action=MagicMock(),+ )++ result = tool_usage.use(+ calling=ToolCalling(+ tool_name="typed_search",+ arguments={"query": "crew"},+ ),+ tool_string='Action: typed_search\nAction Input: {"query": "crew"}',+ )++ assert json.loads(result) == {"query": "crew", "score": 0.7}+ assert raw_results == [SearchOutput(query="crew", score=0.7)]+ tools_handler.on_tool_use.assert_called_once()+ assert tools_handler.on_tool_use.call_args.kwargs["output"] == SearchOutput(+ query="crew",+ score=0.7,+ )+++def test_react_tool_hooks_receive_agent_text_and_raw_cached_typed_output():+ structured_tool = TypedSearchTool().to_structured_tool()+ tools_handler = ToolsHandler(cache=CacheHandler())+ seen_results: list[tuple[str | None, object]] = []++ def after_hook(context: ToolCallHookContext) -> None:+ seen_results.append((context.tool_result, context.raw_tool_result))++ clear_after_tool_call_hooks()+ register_after_tool_call_hook(after_hook)++ action = AgentAction(+ thought="",+ tool="typed_search",+ tool_input='{"query": "crew"}',+ text='Action: typed_search\nAction Input: {"query": "crew"}',+ )++ try:+ first = execute_tool_and_check_finality(+ agent_action=action,+ tools=[structured_tool],+ tools_handler=tools_handler,+ )+ tools_handler.last_used_tool = None+ second = execute_tool_and_check_finality(+ agent_action=action,+ tools=[structured_tool],+ tools_handler=tools_handler,+ )+ finally:+ clear_after_tool_call_hooks()++ assert json.loads(first.result) == {"query": "crew", "score": 0.7}+ assert json.loads(second.result) == {"query": "crew", "score": 0.7}+ assert seen_results == [+ ('{"query":"crew","score":0.7}', SearchOutput(query="crew", score=0.7)),+ ('{"query":"crew","score":0.7}', SearchOutput(query="crew", score=0.7)),+ ]+++def test_last_raw_result_falls_back_only_until_recorded():+ tool_usage = ToolUsage(+ tools_handler=None,+ tools=[],+ task=None,+ function_calling_llm=MagicMock(),+ agent=None,+ action=MagicMock(),+ )++ assert tool_usage.get_last_raw_result("formatted result") == "formatted result"++ tool_usage.last_raw_result = None++ assert tool_usage.get_last_raw_result("formatted result") is None++def test_validate_tool_input_booleans_and_none():tool_usage = ToolUsage(tools_handler=MagicMock(),diff --git a/lib/crewai/tests/utilities/test_agent_utils.py b/lib/crewai/tests/utilities/test_agent_utils.pyindex de3ed411b..9cf4a2d2a 100644--- a/lib/crewai/tests/utilities/test_agent_utils.py+++ b/lib/crewai/tests/utilities/test_agent_utils.py@@ -3,12 +3,19 @@from __future__ import annotationsimport asyncio+import jsonfrom typing import Any, Literal, Optionalfrom unittest.mock import AsyncMock, MagicMock, patchimport pytestfrom pydantic import BaseModel, Field+from crewai.hooks.tool_hooks import (+ ToolCallHookContext,+ clear_after_tool_call_hooks,+ clear_before_tool_call_hooks,+ register_after_tool_call_hook,+)from crewai.tools.base_tool import BaseToolfrom crewai.utilities.agent_utils import (_asummarize_chunks,@@ -1030,6 +1037,142 @@ class TestParseToolCallArgs:class TestExecuteSingleNativeToolCall:"""Tests for execute_single_native_tool_call."""+ def test_typed_tool_output_is_json_agent_text(self) -> None:+ clear_before_tool_call_hooks()+ clear_after_tool_call_hooks()++ class SearchOutput(BaseModel):+ query: str+ score: float++ class TypedSearchTool(BaseTool):+ name: str = "typed_search"+ description: str = "Search for a query"+ result_schema: type[BaseModel] = SearchOutput++ def _run(self, query: str) -> SearchOutput:+ return SearchOutput(query=query, score=0.9)++ tool = TypedSearchTool()+ tool_call = MagicMock()+ tool_call.id = "call_1"+ tool_call.function.name = "typed_search"+ tool_call.function.arguments = '{"query": "crew"}'++ result = execute_single_native_tool_call(+ tool_call,+ available_functions={"typed_search": tool._run},+ original_tools=[tool],+ structured_tools=[tool.to_structured_tool()],+ tools_handler=None,+ agent=None,+ task=None,+ crew=None,+ event_source=MagicMock(),+ printer=None,+ verbose=False,+ )++ assert json.loads(result.result) == {"query": "crew", "score": 0.9}+ assert json.loads(result.tool_message["content"]) == {+ "query": "crew",+ "score": 0.9,+ }++ def test_custom_agent_output_formatter_is_used_from_structured_tool(+ self,+ ) -> None:+ clear_before_tool_call_hooks()+ clear_after_tool_call_hooks()++ class SearchOutput(BaseModel):+ query: str+ score: float++ class MarkdownSearchTool(BaseTool):+ name: str = "markdown_search"+ description: str = "Search for a query"+ result_schema: type[BaseModel] = SearchOutput++ def _run(self, query: str) -> SearchOutput:+ return SearchOutput(query=query, score=0.9)++ def format_output_for_agent(self, raw_result: Any) -> str:+ result = self.result_schema.model_validate(raw_result)+ return f"### {result.query}\n\nScore: **{result.score}**"++ tool = MarkdownSearchTool()+ tool_call = MagicMock()+ tool_call.id = "call_1"+ tool_call.function.name = "markdown_search"+ tool_call.function.arguments = '{"query": "crew"}'++ result = execute_single_native_tool_call(+ tool_call,+ available_functions={"markdown_search": tool._run},+ original_tools=[],+ structured_tools=[tool.to_structured_tool()],+ tools_handler=None,+ agent=None,+ task=None,+ crew=None,+ event_source=MagicMock(),+ printer=None,+ verbose=False,+ )++ assert result.result == "### crew\n\nScore: **0.9**"+ assert result.tool_message["content"] == "### crew\n\nScore: **0.9**"++ def test_after_hook_includes_raw_tool_result_for_typed_output(self) -> None:+ clear_after_tool_call_hooks()++ class SearchOutput(BaseModel):+ query: str+ score: float++ class TypedSearchTool(BaseTool):+ name: str = "typed_search"+ description: str = "Search for a query"+ result_schema: type[BaseModel] = SearchOutput++ def _run(self, query: str) -> SearchOutput:+ return SearchOutput(query=query, score=0.9)++ seen_results: list[tuple[str | None, object]] = []++ def after_hook(context: ToolCallHookContext) -> None:+ seen_results.append((context.tool_result, context.raw_tool_result))++ tool = TypedSearchTool()+ tool_call = MagicMock()+ tool_call.id = "call_1"+ tool_call.function.name = "typed_search"+ tool_call.function.arguments = '{"query": "crew"}'++ register_after_tool_call_hook(after_hook)+ try:+ result = execute_single_native_tool_call(+ tool_call,+ available_functions={"typed_search": tool._run},+ original_tools=[tool],+ structured_tools=[tool.to_structured_tool()],+ tools_handler=None,+ agent=None,+ task=None,+ crew=None,+ event_source=MagicMock(),+ printer=None,+ verbose=False,+ )+ finally:+ clear_after_tool_call_hooks()++ assert json.loads(result.result) == {"query": "crew", "score": 0.9}+ assert seen_results == [+ ('{"query":"crew","score":0.9}', SearchOutput(query="crew", score=0.9))+ ]+def test_result_as_answer_false_on_tool_error(self) -> None:"""When a tool with result_as_answer=True raises, result_as_answer must be False.