Skip to content

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.py
index 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 task
else None,
)
+ if isinstance(self.agent_executor, AgentExecutor):
+ self.agent_executor.use_better_compaction = self.use_better_compaction
def _update_executor_parameters(
self,
@@ -1354,6 +1360,8 @@ class Agent(BaseAgent):
self.agent_executor.tools_handler = self.tools_handler
self.agent_executor.request_within_rpm_limit = rpm_limit_fn
+ if isinstance(self.agent_executor, AgentExecutor):
+ self.agent_executor.use_better_compaction = self.use_better_compaction
def 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_compaction
executor.request_within_rpm_limit = rpm_limit_fn
executor.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.py
index 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_tool
and 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.py
index 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 Panel
from rich.text import Text
from 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 BaseTool
from crewai.tools.structured_tool import CrewStructuredTool
from 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, SystemPromptResult
from crewai.utilities.step_execution_context import StepExecutionContext, StepResult
from 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_finality
from crewai.utilities.training_handler import CrewTrainingHandler
from 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_tool
and 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_tool
and 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 = False
self.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)
raise
finally:
+ self._cleanup_deferred_tool_results()
self._is_executing = False
async 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 = False
self.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)
raise
finally:
+ self._cleanup_deferred_tool_results()
self._is_executing = False
async 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.py
index 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] = 4096
DEFAULT_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
+
@abstractmethod
def 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.py
new file mode 100644
index 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.py
index 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_tool
and 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.py
new file mode 100644
index 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.py
index 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.py
index 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-invoke
diff --git a/lib/crewai/tests/llms/openai/test_openai.py b/lib/crewai/tests/llms/openai/test_openai.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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()) == []