Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat: defer oversized native tool results (#8110)
Vidit Ostwale9f682222a05
diff --git a/lib/crewai/src/crewai/agent/core.py b/lib/crewai/src/crewai/agent/core.pyindex c8d0034b4..929edf781 100644--- a/lib/crewai/src/crewai/agent/core.py+++ b/lib/crewai/src/crewai/agent/core.py@@ -299,6 +299,10 @@ class Agent(BaseAgent):default=True,description="Keep messages under the context window size by summarizing content.",)+ use_better_compaction: bool = Field(+ default=True,+ description="Defer oversized tool results to temporary artifacts for bounded reads.",+ )max_retry_limit: int = Field(default=2,description="Maximum number of retries for an agent to execute a task when an error occurs.",@@ -1307,6 +1311,8 @@ class Agent(BaseAgent):if taskelse None,)+ if isinstance(self.agent_executor, AgentExecutor):+ self.agent_executor.use_better_compaction = self.use_better_compactiondef _update_executor_parameters(self,@@ -1354,6 +1360,8 @@ class Agent(BaseAgent):self.agent_executor.tools_handler = self.tools_handlerself.agent_executor.request_within_rpm_limit = rpm_limit_fn+ if isinstance(self.agent_executor, AgentExecutor):+ self.agent_executor.use_better_compaction = self.use_better_compactiondef get_delegation_tools(self, agents: Sequence[BaseAgent]) -> list[BaseTool]:agent_tools = AgentTools(agents=agents)@@ -1679,6 +1687,7 @@ class Agent(BaseAgent):BaseLLM | None, self.function_calling_llm)executor.respect_context_window = self.respect_context_window+ executor.use_better_compaction = self.use_better_compactionexecutor.request_within_rpm_limit = rpm_limit_fnexecutor.callbacks = [TokenCalcHandler(self._token_process)]else:@@ -1696,6 +1705,7 @@ class Agent(BaseAgent):step_callback=self.step_callback,function_calling_llm=self.function_calling_llm,respect_context_window=self.respect_context_window,+ use_better_compaction=self.use_better_compaction,request_within_rpm_limit=rpm_limit_fn,callbacks=[TokenCalcHandler(self._token_process)],response_model=response_format,diff --git a/lib/crewai/src/crewai/agents/crew_agent_executor.py b/lib/crewai/src/crewai/agents/crew_agent_executor.pyindex bd7d313d3..ec16fa1ac 100644--- a/lib/crewai/src/crewai/agents/crew_agent_executor.py+++ b/lib/crewai/src/crewai/agents/crew_agent_executor.py@@ -1074,7 +1074,6 @@ class CrewAgentExecutor(BaseAgentExecutor):call_id = cast(str, execution_result["call_id"])func_name = cast(str, execution_result["func_name"])result = cast(str, execution_result["result"])- from_cache = cast(bool, execution_result["from_cache"])original_tool = execution_result["original_tool"]tool_message: LLMMessage = {@@ -1085,13 +1084,6 @@ class CrewAgentExecutor(BaseAgentExecutor):}self.messages.append(tool_message)- if self.agent and self.agent.verbose:- cache_info = " (from cache)" if from_cache else ""- PRINTER.print(- content=f"Tool {func_name} executed with result{cache_info}: {result[:200]}...",- color="green",- )-if (original_tooland hasattr(original_tool, "result_as_answer")diff --git a/lib/crewai/src/crewai/experimental/agent_executor.py b/lib/crewai/src/crewai/experimental/agent_executor.pyindex 0449336ab..5fa1a1e69 100644--- a/lib/crewai/src/crewai/experimental/agent_executor.py+++ b/lib/crewai/src/crewai/experimental/agent_executor.py@@ -20,6 +20,7 @@ from pydantic import (model_validator,)from rich.console import Console+from rich.panel import Panelfrom rich.text import Textfrom typing_extensions import Self@@ -73,6 +74,9 @@ from crewai.hooks.types import (BeforeLLMCallHookCallable,BeforeLLMCallHookType,)+from crewai.tools.agent_tools.deferred_tool_result_reader import (+ DeferredToolResultReader,+)from crewai.tools.base_tool import BaseToolfrom crewai.tools.structured_tool import CrewStructuredToolfrom crewai.tools.tool_failure import (@@ -93,6 +97,7 @@ from crewai.utilities.agent_utils import (format_message_for_llm,format_native_tool_output_for_agent,get_llm_response,+ get_tool_names,handle_agent_action_core,handle_context_length,handle_max_iterations_exceeded,@@ -105,6 +110,7 @@ from crewai.utilities.agent_utils import (is_tool_call_list,parse_tool_call_args,process_llm_response,+ render_text_description_and_args,setup_native_tools,track_delegation_if_needed,)@@ -120,6 +126,11 @@ from crewai.utilities.planning_types import (from crewai.utilities.prompts import StandardPromptResult, SystemPromptResultfrom crewai.utilities.step_execution_context import StepExecutionContext, StepResultfrom crewai.utilities.string_utils import sanitize_tool_name+from crewai.utilities.tool_result_artifacts import (+ TOOL_RESULT_PREVIEW_LINE_COUNT,+ TOOL_RESULT_READ_CONTEXT_WINDOW_RATIO,+ ToolResultArtifactStore,+)from crewai.utilities.tool_utils import execute_tool_and_check_finalityfrom crewai.utilities.training_handler import CrewTrainingHandlerfrom crewai.utilities.types import LLMMessage@@ -206,6 +217,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):original_tools: list[BaseTool] = Field(default_factory=list, exclude=True)function_calling_llm: BaseLLM | None = Field(default=None, exclude=True)respect_context_window: bool = Field(default=False, exclude=True)+ use_better_compaction: bool = Field(default=True, exclude=True)request_within_rpm_limit: Callable[[], bool] | None = Field(default=None, exclude=True)@@ -231,6 +243,12 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):_step_executor: Any = PrivateAttr(default=None)_planner_observer: PlannerObserver | None = PrivateAttr(default=None)_is_feedback_iteration: bool = PrivateAttr(default=False)+ _tool_result_artifact_store: ToolResultArtifactStore | None = PrivateAttr(+ default=None+ )+ _deferred_file_reader: Any = PrivateAttr(default=None)+ _deferred_file_reader_added_by_executor: bool = PrivateAttr(default=False)+ _deferred_file_aliases: list[str] = PrivateAttr(default_factory=list)@model_validator(mode="after")def _setup_executor(self) -> Self:@@ -273,6 +291,155 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):self._tool_name_mapping,) = setup_native_tools(self.original_tools)+ def _prepare_tool_result_for_context(self, execution_result: dict[str, Any]) -> str:+ """Replace an oversized successful result with a deferred-file reference."""+ result = cast(str, execution_result["result"])+ if execution_result.get("tool_failure") is not None:+ return result++ original_tool = execution_result.get("original_tool")+ if isinstance(original_tool, DeferredToolResultReader):+ return result++ if getattr(original_tool, "result_as_answer", False):+ return result++ if not self.use_better_compaction:+ return result++ if self.llm is None:+ return result+ try:+ should_defer, token_count = self.llm.is_tool_result_overflowing_threshold(+ result+ )+ except Exception:+ return result+ if not should_defer:+ return result++ if self._tool_result_artifact_store is None:+ self._tool_result_artifact_store = ToolResultArtifactStore()++ artifact = self._tool_result_artifact_store.store(+ result, estimated_token_count=token_count+ )++ reader = next(+ (+ tool+ for tool in self.original_tools+ if isinstance(tool, DeferredToolResultReader)+ ),+ None,+ )+ if reader is None:+ reader = DeferredToolResultReader()+ self._register_deferred_file_reader(reader)+ self._deferred_file_reader = reader+ reader.allow_file(str(artifact.file_path), artifact.relative_path.as_posix())+ self._deferred_file_aliases.append(artifact.relative_path.as_posix())+ reader_name = next(+ name for name, tool in self._tool_name_mapping.items() if tool is reader+ )++ tool_args = json.dumps(+ execution_result.get("tool_args", {}), default=str, sort_keys=True+ )+ preview_suffix = (+ "\n[Preview truncated; read the artifact for more.]"+ if artifact.preview_truncated+ else ""+ )+ average_tokens_per_line = (+ artifact.estimated_token_count / artifact.line_count+ if artifact.line_count+ else 0+ )+ read_target_tokens = max(+ 1,+ round(+ self.llm.get_context_window_size()+ * TOOL_RESULT_READ_CONTEXT_WINDOW_RATIO+ ),+ )+ recommended_line_count = (+ min(+ artifact.line_count,+ max(+ 1,+ round(read_target_tokens / average_tokens_per_line),+ ),+ )+ if average_tokens_per_line+ else 1+ )+ artifact_reference = (+ f"The result of `{execution_result['func_name']}` with arguments "+ f"`{tool_args}` was stored as temporary artifact "+ f"`{artifact.artifact_id}` at relative file path "+ f"`{artifact.relative_path.as_posix()}`. It contains "+ f"{artifact.line_count} lines and is estimated at "+ f"{artifact.estimated_token_count} tokens (about "+ f"{average_tokens_per_line:.1f} tokens per line).\n\nPreview of the first "+ f"{TOOL_RESULT_PREVIEW_LINE_COUNT} lines:\n---\n{artifact.preview}"+ f"{preview_suffix}\n---\n\nUse `{reader_name}` to read it in bounded sections. For a "+ f"roughly {read_target_tokens:,}-token read, request about "+ f"{recommended_line_count} lines, for example with `start_line=1` and "+ f"`line_count={recommended_line_count}`."+ )+ if self.agent and self.agent.verbose:+ self._console.print(+ Panel(+ Text(artifact_reference),+ title="📦 Large tool result deferred",+ border_style="yellow",+ padding=(1, 2),+ )+ )+ return artifact_reference++ def _cleanup_deferred_tool_results(self) -> None:+ """Remove temporary tool-result files and their reader aliases."""+ reader = self._deferred_file_reader+ for alias in self._deferred_file_aliases:+ if reader is not None:+ reader.disallow_file(alias)++ if self._deferred_file_reader_added_by_executor and reader is not None:+ if reader in self.original_tools:+ self.original_tools.remove(reader)+ if self.original_tools:+ self._setup_native_tools()+ else:+ self._openai_tools = []+ self._available_functions = {}+ self._tool_name_mapping = {}+ self.tools = [+ tool+ for tool in self.tools+ if getattr(tool, "_original_tool", None) is not reader+ ]+ self.tools_names = get_tool_names(self.tools)+ self.tools_description = render_text_description_and_args(self.tools)++ if self._tool_result_artifact_store is not None:+ self._tool_result_artifact_store.cleanup()++ self._tool_result_artifact_store = None+ self._deferred_file_reader = None+ self._deferred_file_reader_added_by_executor = False+ self._deferred_file_aliases.clear()++ def _register_deferred_file_reader(self, reader: DeferredToolResultReader) -> None:+ """Expose an executor-owned reader to native and text tool calling."""+ self.original_tools.append(reader)+ self.tools.append(reader.to_structured_tool())+ self._setup_native_tools()+ self.tools_names = get_tool_names(self.tools)+ self.tools_description = render_text_description_and_args(self.tools)+ self._deferred_file_reader_added_by_executor = True+def _downgrade_to_text_tool_calling(self) -> None:"""Switch a running execution from native tools to text tool calls."""self.state.use_native_tools = False@@ -1840,8 +2007,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):execution_result = self._execute_single_native_tool_call(tool_call)call_id = cast(str, execution_result["call_id"])func_name = cast(str, execution_result["func_name"])- result = cast(str, execution_result["result"])- from_cache = cast(bool, execution_result["from_cache"])+ result = self._prepare_tool_result_for_context(execution_result)original_tool = execution_result["original_tool"]tool_message: LLMMessage = {@@ -1852,14 +2018,6 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):}self.state.messages.append(tool_message)- # Log the tool execution- if self.agent and self.agent.verbose:- cache_info = " (from cache)" if from_cache else ""- PRINTER.print(- content=f"Tool {func_name} executed with result{cache_info}: {result[:200]}...",- color="green",- )-if (original_tooland hasattr(original_tool, "result_as_answer")@@ -1880,8 +2038,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):for execution_result in execution_results:call_id = cast(str, execution_result["call_id"])func_name = cast(str, execution_result["func_name"])- result = cast(str, execution_result["result"])- from_cache = cast(bool, execution_result["from_cache"])+ result = self._prepare_tool_result_for_context(execution_result)original_tool = execution_result["original_tool"]tool_message = {@@ -1892,14 +2049,6 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):}self.state.messages.append(tool_message)- # Log the tool execution- if self.agent and self.agent.verbose:- cache_info = " (from cache)" if from_cache else ""- PRINTER.print(- content=f"Tool {func_name} executed with result{cache_info}: {result[:200]}...",- color="green",- )-if (original_tooland hasattr(original_tool, "result_as_answer")@@ -2184,6 +2333,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):"call_id": call_id,"func_name": func_name,"result": result,+ "tool_args": args_dict,"from_cache": from_cache,"original_tool": original_tool,"tool_failure": tool_failure,@@ -2877,6 +3027,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):try:# Reset state for fresh execution+ self._cleanup_deferred_tool_results()self._finalize_called = Falseself.state.messages.clear()self.state.iterations = 0@@ -2937,6 +3088,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):handle_unknown_error(PRINTER, e, verbose=self.agent.verbose)raisefinally:+ self._cleanup_deferred_tool_results()self._is_executing = Falseasync def invoke_async(self, inputs: dict[str, Any]) -> dict[str, Any]:@@ -2963,6 +3115,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):try:# Reset state for fresh execution+ self._cleanup_deferred_tool_results()self._finalize_called = Falseself.state.messages.clear()self.state.iterations = 0@@ -3025,6 +3178,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):handle_unknown_error(PRINTER, e, verbose=self.agent.verbose)raisefinally:+ self._cleanup_deferred_tool_results()self._is_executing = Falseasync def ainvoke(self, inputs: dict[str, Any]) -> dict[str, Any]:diff --git a/lib/crewai/src/crewai/llms/base_llm.py b/lib/crewai/src/crewai/llms/base_llm.pyindex 33a511070..7a7c0cde0 100644--- a/lib/crewai/src/crewai/llms/base_llm.py+++ b/lib/crewai/src/crewai/llms/base_llm.py@@ -85,6 +85,7 @@ class LLMCallBlockedError(ValueError):DEFAULT_CONTEXT_WINDOW_SIZE: Final[int] = 4096DEFAULT_SUPPORTS_STOP_WORDS: Final[bool] = True+TOOL_RESULT_CONTEXT_WINDOW_THRESHOLD: Final[float] = 0.25_JSON_EXTRACTION_PATTERN: Final[re.Pattern[str]] = re.compile(r"\{.*}", re.DOTALL)logger = logging.getLogger(__name__)@@ -401,6 +402,28 @@ class BaseLLM(BaseModel, ABC):)return (character_count + 3) // 4+ def is_tool_result_overflowing_threshold(+ self, tool_result: str+ ) -> tuple[bool, int]:+ """Check whether a tool result exceeds the deferred-output threshold.++ The threshold is 25% of the model's usable context window. The count+ comes from one call to :meth:`get_input_tokens_count`, which uses the+ provider's estimator or the four-characters-per-token fallback.++ Args:+ tool_result: The formatted text returned by a tool.++ Returns:+ Whether the result alone uses more than 25% of the usable context+ window, and the input-token count from that same check.+ """+ tool_result_tokens = self.get_input_tokens_count(tool_result)+ threshold = (+ self.get_context_window_size() * TOOL_RESULT_CONTEXT_WINDOW_THRESHOLD+ )+ return tool_result_tokens > threshold, tool_result_tokens+@abstractmethoddef call(self,diff --git a/lib/crewai/src/crewai/tools/agent_tools/deferred_tool_result_reader.py b/lib/crewai/src/crewai/tools/agent_tools/deferred_tool_result_reader.pynew file mode 100644index 000000000..f245d5098--- /dev/null+++ b/lib/crewai/src/crewai/tools/agent_tools/deferred_tool_result_reader.py@@ -0,0 +1,73 @@+"""Bounded reader for temporary native-tool result artifacts."""++from __future__ import annotations++from itertools import islice+from os import path++from pydantic import BaseModel, Field, PrivateAttr++from crewai.tools.base_tool import BaseTool+++class DeferredToolResultReaderSchema(BaseModel):+ """Input accepted by the deferred tool-result reader."""++ file_path: str = Field(+ ..., description="The temporary artifact path supplied in the tool result."+ )+ start_line: int | None = Field(+ default=1, description="Line number to start reading from (1-indexed)."+ )+ line_count: int | None = Field(default=None, description="Number of lines to read.")+++class DeferredToolResultReader(BaseTool):+ """Read framework-managed deferred tool results through exact aliases only."""++ name: str = "Read a deferred tool result"+ description: str = (+ "Read a bounded section of a temporary tool-result artifact. "+ "Only artifact paths supplied by a previous tool result are available."+ )+ args_schema: type[BaseModel] = DeferredToolResultReaderSchema++ _allowed_file_paths: dict[str, str] = PrivateAttr(default_factory=dict)++ def allow_file(self, file_path: str, alias: str) -> None:+ """Allow an exact temporary artifact path for this execution."""+ if not alias:+ raise ValueError("Allowed file aliases must not be empty.")+ self._allowed_file_paths[alias] = path.realpath(file_path)++ def disallow_file(self, alias: str) -> None:+ """Revoke an artifact path. Missing aliases are ignored."""+ self._allowed_file_paths.pop(alias, None)++ def _run(+ self,+ file_path: str,+ start_line: int | None = 1,+ line_count: int | None = None,+ ) -> str:+ """Read a complete artifact or a bounded line range."""+ resolved_path = self._allowed_file_paths.get(file_path)+ if resolved_path is None:+ return "Error: This temporary tool-result artifact is not available."++ start_index = max((start_line or 1) - 1, 0)+ try:+ with open(resolved_path, encoding="utf-8") as artifact_file:+ if start_index == 0 and line_count is None:+ return artifact_file.read()++ stop_index = (+ None if line_count is None else start_index + max(line_count, 0)+ )+ lines = list(islice(artifact_file, start_index, stop_index))+ except FileNotFoundError:+ return "Error: Temporary tool-result artifact is no longer available."++ if not lines and start_index > 0:+ return f"Error: Start line {start_line} exceeds the number of lines in the artifact."+ return "".join(lines)diff --git a/lib/crewai/src/crewai/utilities/agent_utils.py b/lib/crewai/src/crewai/utilities/agent_utils.pyindex 61739c54f..a446f5c9d 100644--- a/lib/crewai/src/crewai/utilities/agent_utils.py+++ b/lib/crewai/src/crewai/utilities/agent_utils.py@@ -1893,13 +1893,6 @@ def execute_single_native_tool_call("content": result,}- if verbose and printer:- cache_info = " (from cache)" if from_cache else ""- printer.print(- content=f"Tool {func_name} executed with result{cache_info}: {result[:200]}...",- color="green",- )-is_result_as_answer = bool(original_tooland hasattr(original_tool, "result_as_answer")diff --git a/lib/crewai/src/crewai/utilities/tool_result_artifacts.py b/lib/crewai/src/crewai/utilities/tool_result_artifacts.pynew file mode 100644index 000000000..42bf23f43--- /dev/null+++ b/lib/crewai/src/crewai/utilities/tool_result_artifacts.py@@ -0,0 +1,93 @@+"""Private, temporary storage for deferred tool results."""++from __future__ import annotations++from dataclasses import dataclass+from pathlib import Path+from secrets import token_urlsafe+from tempfile import TemporaryDirectory+++TOOL_RESULT_PREVIEW_LINE_COUNT = 10+TOOL_RESULT_PREVIEW_MAX_CHARS = 2_000+TOOL_RESULT_READ_CONTEXT_WINDOW_RATIO = 0.05+++@dataclass(frozen=True)+class ToolResultArtifact:+ """An internally-addressable deferred tool result."""++ artifact_id: str+ directory: Path+ relative_path: Path+ file_path: Path+ line_count: int+ estimated_token_count: int+ preview: str+ preview_truncated: bool+++class ToolResultArtifactStore:+ """Store tool results outside the conversation for one execution.++ Artifact identifiers are opaque capabilities scoped to this store. Each+ result gets an isolated directory so a pre-bound file tool can expose only+ that result. The temporary directory is removed by :meth:`cleanup` when+ the execution ends.+ """++ def __init__(self, base_dir: Path | None = None) -> None:+ """Create an execution-scoped store under the system temp directory.++ Args:+ base_dir: Parent directory for the private execution directory.+ Intended for tests; production defaults to the system temp+ directory.+ """+ directory = str(base_dir) if base_dir is not None else None+ self._temporary_directory = TemporaryDirectory(+ prefix="crewai-tool-results-", dir=directory+ )+ self._directory = Path(self._temporary_directory.name)+ self._artifact_ids: set[str] = set()++ def store(self, content: str, estimated_token_count: int) -> ToolResultArtifact:+ """Persist content and return its internal binding details.++ Args:+ content: Tool result text to store.+ estimated_token_count: Token count already produced for this content.+ """+ artifact_id = f"tool-result-{token_urlsafe(16)}"+ artifact_directory = self._directory / artifact_id+ artifact_directory.mkdir(mode=0o700)+ path = artifact_directory / "result.md"+ path.write_text(content, encoding="utf-8")+ self._artifact_ids.add(artifact_id)+ preview_lines = content.splitlines(keepends=True)+ line_count = len(preview_lines)+ preview = "".join(preview_lines[:TOOL_RESULT_PREVIEW_LINE_COUNT])+ preview_truncated = len(preview_lines) > TOOL_RESULT_PREVIEW_LINE_COUNT+ if len(preview) > TOOL_RESULT_PREVIEW_MAX_CHARS:+ preview = preview[:TOOL_RESULT_PREVIEW_MAX_CHARS]+ preview_truncated = True+ return ToolResultArtifact(+ artifact_id=artifact_id,+ directory=self._directory,+ relative_path=path.relative_to(self._directory),+ file_path=path,+ line_count=line_count,+ estimated_token_count=estimated_token_count,+ preview=preview,+ preview_truncated=preview_truncated,+ )++ @property+ def directory(self) -> Path:+ """Return the private root directory for this execution's artifacts."""+ return self._directory++ def cleanup(self) -> None:+ """Delete every artifact in this execution. Safe to call repeatedly."""+ self._artifact_ids.clear()+ self._temporary_directory.cleanup()diff --git a/lib/crewai/tests/agents/test_agent.py b/lib/crewai/tests/agents/test_agent.pyindex abff33592..9e8fc2cac 100644--- a/lib/crewai/tests/agents/test_agent.py+++ b/lib/crewai/tests/agents/test_agent.py@@ -949,6 +949,20 @@ def test_using_system_prompt():assert agent.agent_executor.prompt.get("system")+def test_agent_passes_better_compaction_setting_to_executor():+ agent = Agent(+ role="test role",+ goal="test goal",+ backstory="test backstory",+ use_better_compaction=False,+ )++ agent.create_agent_executor()++ assert agent.agent_executor is not None+ assert agent.agent_executor.use_better_compaction is False++def test_system_and_prompt_template():agent = Agent(role="{topic} specialist",diff --git a/lib/crewai/tests/agents/test_agent_executor.py b/lib/crewai/tests/agents/test_agent_executor.pyindex f09d4c429..3583006c7 100644--- a/lib/crewai/tests/agents/test_agent_executor.py+++ b/lib/crewai/tests/agents/test_agent_executor.py@@ -2420,6 +2420,488 @@ class TestNativeToolCallMaxUsage:assert 'result = f"Tool \'{func_name}\' has reached its maximum usage limit' in source+class TestDeferredNativeToolResults:+ """Oversized native results are stored outside the next LLM request."""++ @pytest.mark.parametrize(+ "overflow_result",+ [False, NotImplementedError, RuntimeError],+ ids=[+ "within_threshold",+ "token_estimation_unsupported",+ "token_estimation_failed",+ ],+ )+ def test_result_stays_inline_when_deferral_is_unavailable(self, overflow_result):+ llm = Mock()+ if overflow_result in (NotImplementedError, RuntimeError):+ llm.is_tool_result_overflowing_threshold.side_effect = overflow_result+ else:+ llm.is_tool_result_overflowing_threshold.return_value = (False, 10)+ executor = _build_executor(llm=llm, original_tools=[])+ result = "small tool result"++ context_result = executor._prepare_tool_result_for_context(+ {+ "func_name": "search_docs",+ "result": result,+ "tool_args": {"query": "CrewAI"},+ "original_tool": None,+ "tool_failure": None,+ }+ )++ assert context_result == result+ assert executor._tool_result_artifact_store is None+ assert executor.original_tools == []++ def test_result_stays_inline_when_better_compaction_is_disabled(self):+ llm = Mock()+ executor = _build_executor(+ llm=llm,+ original_tools=[],+ use_better_compaction=False,+ )+ result = "oversized tool result"++ context_result = executor._prepare_tool_result_for_context(+ {+ "func_name": "search_docs",+ "result": result,+ "tool_args": {"query": "CrewAI"},+ "original_tool": None,+ "tool_failure": None,+ }+ )++ assert context_result == result+ assert executor._tool_result_artifact_store is None+ assert executor.original_tools == []+ llm.is_tool_result_overflowing_threshold.assert_not_called()++ def test_deferred_reader_result_is_not_deferred_again(self):+ from crewai.tools.agent_tools.deferred_tool_result_reader import (+ DeferredToolResultReader,+ )++ llm = Mock()+ reader = DeferredToolResultReader()+ executor = _build_executor(llm=llm, original_tools=[reader])+ result = "large deferred tool result"++ context_result = executor._prepare_tool_result_for_context(+ {+ "func_name": reader.name,+ "result": result,+ "tool_args": {"file_path": "artifact/result.md"},+ "original_tool": reader,+ "tool_failure": None,+ }+ )++ assert context_result == result+ assert executor._tool_result_artifact_store is None+ llm.is_tool_result_overflowing_threshold.assert_not_called()++ def test_overflowed_result_is_referenced_and_readable_through_file_reader(self):+ from crewai.tools.agent_tools.deferred_tool_result_reader import (+ DeferredToolResultReader,+ )++ llm = Mock()+ llm.is_tool_result_overflowing_threshold.return_value = (True, 48)+ llm.get_context_window_size.return_value = 10_000+ executor = _build_executor(+ llm=llm,+ original_tools=[],+ agent=SimpleNamespace(verbose=True),+ )+ executor._console = Mock()+ executor._tool_result_artifact_store = None+ tool_output = "".join(f"line {index}\n" for index in range(12))++ reference = executor._prepare_tool_result_for_context(+ {+ "func_name": "search_docs",+ "result": tool_output,+ "tool_args": {"query": "[unclosed"},+ "original_tool": None,+ "tool_failure": None,+ }+ )++ try:+ artifact_store = executor._tool_result_artifact_store+ assert artifact_store is not None+ reader = next(+ tool+ for tool in executor.original_tools+ if isinstance(tool, DeferredToolResultReader)+ )+ artifact = next(artifact_store.directory.glob("*/result.md"))+ alias = artifact.relative_to(artifact_store.directory).as_posix()++ assert "search_docs" in reference+ assert '"query": "[unclosed"' in reference+ assert "It contains 12 lines and is estimated at 48 tokens" in reference+ assert "about 4.0 tokens per line" in reference+ reader_name = next(+ name+ for name, tool in executor._tool_name_mapping.items()+ if tool is reader+ )+ assert f"Use `{reader_name}` to read it in bounded sections" in reference+ assert "roughly 500-token read, request about 12 lines" in reference+ assert "Preview of the first 10 lines" in reference+ assert "line 9" in reference+ assert "line 10" not in reference+ panel = executor._console.print.call_args.args[0]+ assert panel.renderable.plain == reference+ assert str(panel.title) == "📦 Large tool result deferred"+ assert reader.run(file_path=alias, start_line=11, line_count=2) == (+ "line 10\nline 11\n"+ )+ finally:+ if executor._tool_result_artifact_store is not None:+ executor._tool_result_artifact_store.cleanup()++ def test_multiple_overflowed_results_reuse_one_file_reader(self):+ from crewai.tools.agent_tools.deferred_tool_result_reader import (+ DeferredToolResultReader,+ )++ llm = Mock()+ llm.is_tool_result_overflowing_threshold.return_value = (True, 1_000)+ llm.get_context_window_size.return_value = 10_000+ executor = _build_executor(llm=llm, original_tools=[])+ executor._tool_result_artifact_store = None++ first_reference = executor._prepare_tool_result_for_context(+ {+ "func_name": "search_docs",+ "result": "first deferred result",+ "tool_args": {"query": "first"},+ "original_tool": None,+ "tool_failure": None,+ }+ )+ second_reference = executor._prepare_tool_result_for_context(+ {+ "func_name": "fetch_page",+ "result": "second deferred result",+ "tool_args": {"url": "https://example.com"},+ "original_tool": None,+ "tool_failure": None,+ }+ )++ try:+ artifact_store = executor._tool_result_artifact_store+ assert artifact_store is not None+ assert len(+ [+ tool+ for tool in executor.original_tools+ if isinstance(tool, DeferredToolResultReader)+ ]+ ) == 1+ assert len(list(artifact_store.directory.glob("*/result.md"))) == 2+ assert first_reference != second_reference+ assert "search_docs" in first_reference+ assert "fetch_page" in second_reference+ assert (+ len(+ [+ tool+ for tool in executor.tools+ if isinstance(+ getattr(tool, "_original_tool", None),+ DeferredToolResultReader,+ )+ ]+ )+ == 1+ )+ finally:+ if executor._tool_result_artifact_store is not None:+ executor._tool_result_artifact_store.cleanup()++ def test_deferred_reader_stays_callable_after_text_tool_downgrade(self):+ from crewai.tools.agent_tools.deferred_tool_result_reader import (+ DeferredToolResultReader,+ )+ from crewai.tools.structured_tool import CrewStructuredTool+ from crewai.utilities.agent_utils import (+ get_tool_names,+ render_text_description_and_args,+ )+ from crewai.utilities.string_utils import sanitize_tool_name++ def lookup_notes(query: str) -> str:+ """Look up notes."""+ return query++ existing = CrewStructuredTool.from_function(lookup_notes, name="lookup_notes")+ llm = Mock()+ llm.is_tool_result_overflowing_threshold.return_value = (True, 1_000)+ llm.get_context_window_size.return_value = 10_000+ executor = _build_executor(+ llm=llm,+ original_tools=[],+ tools=[existing],+ tools_names=get_tool_names([existing]),+ tools_description=render_text_description_and_args([existing]),+ )+ executor._tool_result_artifact_store = None+ executor.state.messages = [{"role": "user", "content": "Use a tool"}]++ executor._prepare_tool_result_for_context(+ {+ "func_name": "search_docs",+ "result": "deferred content",+ "tool_args": {"query": "CrewAI"},+ "original_tool": None,+ "tool_failure": None,+ }+ )++ try:+ artifact_store = executor._tool_result_artifact_store+ assert artifact_store is not None+ artifact = next(artifact_store.directory.glob("*/result.md"))+ alias = artifact.relative_to(artifact_store.directory).as_posix()+ reader = next(+ tool+ for tool in executor.original_tools+ if isinstance(tool, DeferredToolResultReader)+ )+ structured_readers = [+ tool+ for tool in executor.tools+ if getattr(tool, "_original_tool", None) is reader+ ]+ reader_name = sanitize_tool_name(reader.name)++ assert executor.tools[0] is existing+ assert len(structured_readers) == 1+ assert reader_name in executor.tools_names+ assert "lookup_notes" in executor.tools_names+ assert f"Tool Name: {reader_name}" in executor.tools_description+ assert structured_readers[0].invoke({"file_path": alias}) == (+ "deferred content"+ )++ executor._downgrade_to_text_tool_calling()++ fallback = executor.state.messages[-1]["content"]+ assert isinstance(fallback, str)+ assert reader_name in fallback+ assert "lookup_notes" in fallback+ assert executor.state.use_native_tools is False+ finally:+ executor._cleanup_deferred_tool_results()++ assert executor.tools == [existing]+ assert executor.tools_names == get_tool_names([existing])+ assert executor.tools_description == render_text_description_and_args(+ [existing]+ )+ assert executor.original_tools == []++ def test_existing_file_reader_keeps_local_access_when_artifact_reader_is_added(+ self, tmp_path+ ):+ from crewai_tools import FileReadTool+ from crewai.tools.agent_tools.deferred_tool_result_reader import (+ DeferredToolResultReader,+ )++ local_files = tmp_path / "local-files"+ local_files.mkdir()+ (local_files / "notes.md").write_text("local content")+ reader = FileReadTool(base_dir=str(local_files))+ llm = Mock()+ llm.is_tool_result_overflowing_threshold.return_value = (True, 1_000)+ llm.get_context_window_size.return_value = 10_000+ executor = _build_executor(llm=llm, original_tools=[reader])+ executor._tool_result_artifact_store = None++ executor._prepare_tool_result_for_context(+ {+ "func_name": "search_docs",+ "result": "deferred content",+ "tool_args": {"query": "CrewAI"},+ "original_tool": None,+ "tool_failure": None,+ }+ )++ try:+ artifact_store = executor._tool_result_artifact_store+ assert artifact_store is not None+ artifact = next(artifact_store.directory.glob("*/result.md"))+ alias = artifact.relative_to(artifact_store.directory).as_posix()++ deferred_reader = next(+ tool+ for tool in executor.original_tools+ if isinstance(tool, DeferredToolResultReader)+ )+ assert reader.run(file_path="notes.md") == "local content"+ assert deferred_reader.run(file_path=alias) == "deferred content"+ finally:+ if executor._tool_result_artifact_store is not None:+ executor._tool_result_artifact_store.cleanup()++ def test_cleanup_removes_artifact_and_revokes_existing_reader_alias(self, tmp_path):+ from crewai_tools import FileReadTool+ from crewai.tools.agent_tools.deferred_tool_result_reader import (+ DeferredToolResultReader,+ )++ local_files = tmp_path / "local-files"+ local_files.mkdir()+ (local_files / "notes.md").write_text("local content")+ reader = FileReadTool(base_dir=str(local_files))+ llm = Mock()+ llm.is_tool_result_overflowing_threshold.return_value = (True, 1_000)+ llm.get_context_window_size.return_value = 10_000+ executor = _build_executor(llm=llm, original_tools=[reader])++ executor._prepare_tool_result_for_context(+ {+ "func_name": "search_docs",+ "result": "deferred content",+ "tool_args": {"query": "CrewAI"},+ "original_tool": None,+ "tool_failure": None,+ }+ )+ artifact_store = executor._tool_result_artifact_store+ assert artifact_store is not None+ artifact_directory = artifact_store.directory+ alias = next(artifact_directory.glob("*/result.md")).relative_to(+ artifact_directory+ ).as_posix()+ deferred_reader = next(+ tool+ for tool in executor.original_tools+ if isinstance(tool, DeferredToolResultReader)+ )++ executor._cleanup_deferred_tool_results()++ assert not artifact_directory.exists()+ assert reader.run(file_path="notes.md") == "local content"+ assert "not available" in deferred_reader.run(file_path=alias)+ assert executor.original_tools == [reader]++ def test_invoke_cleans_deferred_artifacts_after_completion(self):+ from crewai.tools.agent_tools.deferred_tool_result_reader import (+ DeferredToolResultReader,+ )++ llm = Mock()+ llm.is_tool_result_overflowing_threshold.return_value = (True, 1_000)+ llm.get_context_window_size.return_value = 10_000+ executor = _build_executor(+ agent=SimpleNamespace(verbose=False),+ crew=None,+ llm=llm,+ prompt=Mock(),+ original_tools=[],+ )+ executor._setup_messages = Mock()+ executor._inject_files_from_inputs = Mock()+ executor._save_to_memory = Mock()+ artifact_directory = None++ def complete_with_deferred_result() -> None:+ nonlocal artifact_directory+ executor._prepare_tool_result_for_context(+ {+ "func_name": "search_docs",+ "result": "deferred content",+ "tool_args": {"query": "CrewAI"},+ "original_tool": None,+ "tool_failure": None,+ }+ )+ artifact_store = executor._tool_result_artifact_store+ assert artifact_store is not None+ artifact_directory = artifact_store.directory+ executor.state.current_answer = AgentFinish(+ thought="", output="done", text="done"+ )++ executor.kickoff = complete_with_deferred_result++ assert executor.invoke({"input": "Find CrewAI docs"}) == {"output": "done"}+ assert artifact_directory is not None+ assert not artifact_directory.exists()+ assert not any(+ isinstance(tool, DeferredToolResultReader) for tool in executor.original_tools+ )++ @pytest.mark.asyncio+ @pytest.mark.parametrize("should_fail", [False, True], ids=["success", "error"])+ async def test_invoke_async_cleans_deferred_artifacts(self, should_fail):+ from crewai.tools.agent_tools.deferred_tool_result_reader import (+ DeferredToolResultReader,+ )++ llm = Mock()+ llm.is_tool_result_overflowing_threshold.return_value = (True, 1_000)+ llm.get_context_window_size.return_value = 10_000+ executor = _build_executor(+ agent=SimpleNamespace(verbose=False),+ crew=None,+ llm=llm,+ prompt=Mock(),+ original_tools=[],+ )+ executor._setup_messages = Mock()+ executor._ainject_files_from_inputs = AsyncMock()+ executor._save_to_memory = Mock()+ artifact_directory = None++ async def complete_with_deferred_result() -> None:+ nonlocal artifact_directory+ executor._prepare_tool_result_for_context(+ {+ "func_name": "search_docs",+ "result": "deferred content",+ "tool_args": {"query": "CrewAI"},+ "original_tool": None,+ "tool_failure": None,+ }+ )+ artifact_store = executor._tool_result_artifact_store+ assert artifact_store is not None+ artifact_directory = artifact_store.directory+ if should_fail:+ raise RuntimeError("tool execution failed")+ executor.state.current_answer = AgentFinish(+ thought="", output="done", text="done"+ )++ executor.kickoff_async = complete_with_deferred_result++ if should_fail:+ with pytest.raises(RuntimeError, match="tool execution failed"):+ await executor.invoke_async({"input": "Find CrewAI docs"})+ else:+ assert await executor.invoke_async({"input": "Find CrewAI docs"}) == {+ "output": "done"+ }++ assert artifact_directory is not None+ assert not artifact_directory.exists()+ assert not any(+ isinstance(tool, DeferredToolResultReader) for tool in executor.original_tools+ )++# Executor State Reset on Re-invokediff --git a/lib/crewai/tests/llms/openai/test_openai.py b/lib/crewai/tests/llms/openai/test_openai.pyindex 1a7706f02..57cf58b83 100644--- a/lib/crewai/tests/llms/openai/test_openai.py+++ b/lib/crewai/tests/llms/openai/test_openai.py@@ -941,6 +941,26 @@ def test_openai_input_token_count_falls_back_after_api_errors(caplog):assert "assuming one token per four characters" in caplog.text+ ("input_tokens", "expected"),+ [(250, False), (251, True)],+)+def test_openai_tool_result_overflow_threshold_uses_input_token_count(+ input_tokens: int, expected: bool+):+ """A result over one quarter of the usable context window is deferred."""+ llm = OpenAICompletion(model="gpt-4o")++ with (+ patch.object(llm, "get_input_tokens_count", return_value=input_tokens),+ patch.object(llm, "get_context_window_size", return_value=1_000),+ ):+ assert llm.is_tool_result_overflowing_threshold("tool output") == (+ expected,+ input_tokens,+ )++@pytest.mark.vcr(record_mode="once")def test_openai_input_token_count_live():"""OpenAI returns a positive input-token count for a real request."""diff --git a/lib/crewai/tests/tools/agent_tools/test_deferred_tool_result_reader.py b/lib/crewai/tests/tools/agent_tools/test_deferred_tool_result_reader.pynew file mode 100644index 000000000..c7e53d41a--- /dev/null+++ b/lib/crewai/tests/tools/agent_tools/test_deferred_tool_result_reader.py@@ -0,0 +1,30 @@+"""Tests for the framework-owned deferred-result reader."""++from crewai.tools.agent_tools.deferred_tool_result_reader import (+ DeferredToolResultReader,+)+++def test_reads_only_an_allowed_artifact(tmp_path):+ artifact = tmp_path / "result.md"+ artifact.write_text("first\nsecond\nthird\n")+ other_file = tmp_path / "other.md"+ other_file.write_text("must not be readable")+ reader = DeferredToolResultReader()+ reader.allow_file(str(artifact), "artifact/result.md")++ assert reader.run(+ file_path="artifact/result.md", start_line=2, line_count=1+ ) == "second\n"+ assert "not available" in reader.run(file_path=str(other_file))+++def test_revokes_an_artifact_alias(tmp_path):+ artifact = tmp_path / "result.md"+ artifact.write_text("content")+ reader = DeferredToolResultReader()+ reader.allow_file(str(artifact), "artifact/result.md")++ reader.disallow_file("artifact/result.md")++ assert "not available" in reader.run(file_path="artifact/result.md")diff --git a/lib/crewai/tests/utilities/test_tool_result_artifacts.py b/lib/crewai/tests/utilities/test_tool_result_artifacts.pynew file mode 100644index 000000000..3645f4a7a--- /dev/null+++ b/lib/crewai/tests/utilities/test_tool_result_artifacts.py@@ -0,0 +1,65 @@+from pathlib import Path++from crewai.utilities.tool_result_artifacts import ToolResultArtifactStore+++def test_store_returns_opaque_identifier_and_preserves_content(tmp_path: Path) -> None:+ store = ToolResultArtifactStore(base_dir=tmp_path)++ artifact = store.store("first line\nsecond line", estimated_token_count=9)++ assert artifact.artifact_id.startswith("tool-result-")+ assert artifact.directory == store.directory+ assert artifact.relative_path == Path(artifact.artifact_id) / "result.md"+ assert artifact.file_path.name == "result.md"+ assert artifact.file_path.read_text(encoding="utf-8") == "first line\nsecond line"+ assert artifact.line_count == 2+ assert artifact.estimated_token_count == 9++ store.cleanup()+++def test_each_result_has_a_separate_private_file(tmp_path: Path) -> None:+ store = ToolResultArtifactStore(base_dir=tmp_path)+ first = store.store("first result", estimated_token_count=3)+ second = store.store("second result", estimated_token_count=4)++ assert first.artifact_id != second.artifact_id+ assert first.file_path.parent != second.file_path.parent+ assert first.file_path.read_text(encoding="utf-8") == "first result"+ assert second.file_path.read_text(encoding="utf-8") == "second result"++ store.cleanup()+++def test_store_keeps_a_bounded_preview_of_the_first_ten_lines(tmp_path: Path) -> None:+ store = ToolResultArtifactStore(base_dir=tmp_path)+ content = "".join(f"line {index}\n" for index in range(12))++ artifact = store.store(content, estimated_token_count=20)++ assert artifact.preview == "".join(f"line {index}\n" for index in range(10))+ assert artifact.preview_truncated is True++ store.cleanup()+++def test_store_caps_a_single_long_preview_line(tmp_path: Path) -> None:+ store = ToolResultArtifactStore(base_dir=tmp_path)++ artifact = store.store("x" * 2_001, estimated_token_count=501)++ assert len(artifact.preview) == 2_000+ assert artifact.preview_truncated is True++ store.cleanup()+++def test_cleanup_removes_execution_directory_and_is_idempotent(tmp_path: Path) -> None:+ store = ToolResultArtifactStore(base_dir=tmp_path)+ store.store("content", estimated_token_count=2)++ store.cleanup()+ store.cleanup()++ assert list(tmp_path.iterdir()) == []