Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
fix(tools)!: make tool-result caching opt-in instead of on by default (#6509)
João Moura4fdb7f2bfbbd
diff --git a/lib/crewai/src/crewai/agent/core.py b/lib/crewai/src/crewai/agent/core.pyindex 4f4c2368c..4c20693a8 100644--- a/lib/crewai/src/crewai/agent/core.py+++ b/lib/crewai/src/crewai/agent/core.py@@ -401,10 +401,29 @@ class Agent(BaseAgent):return self.planning_config is not None or self.planningdef _setup_agent_executor(self) -> None:- """Initialize the agent executor with a default cache handler."""- if not self.cache_handler:- self.cache_handler = CacheHandler()- self.set_cache_handler(self.cache_handler)+ """Initialize the agent's tools handler and optional tool cache.++ Tool-result caching is opt-in: a standalone agent gets a cache only+ when it was constructed with an explicit ``cache=True`` or a+ ``cache_handler``. Agents inside a crew additionally receive the+ crew's shared handler when ``Crew(cache=True)``. Without an opt-in,+ repeated tool calls with identical arguments always re-execute the+ tool — the safe default for live-data and state-mutating tools.+ """+ # Recorded before any crew can offer its shared handler at kickoff,+ # so copy() can distinguish a construction-time opt-in from runtime+ # crew wiring (which must not turn copies into cachers).+ self._constructor_cache_opt_in = bool(+ self.cache+ and (self.cache_handler is not None or "cache" in self.model_fields_set)+ )+ opted_in = self.cache_handler is not None or (+ "cache" in self.model_fields_set and self.cache+ )+ if opted_in:+ if not self.cache_handler:+ self.cache_handler = CacheHandler()+ self.set_cache_handler(self.cache_handler)def set_knowledge(self, crew_embedder: EmbedderConfig | None = None) -> None:"""Initialize knowledge sources with the agent or crew embedder config."""diff --git a/lib/crewai/src/crewai/agents/agent_builder/base_agent.py b/lib/crewai/src/crewai/agents/agent_builder/base_agent.pyindex a12a4c18b..4530f9527 100644--- a/lib/crewai/src/crewai/agents/agent_builder/base_agent.py+++ b/lib/crewai/src/crewai/agents/agent_builder/base_agent.py@@ -205,7 +205,11 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):role (str): Role of the agent.goal (str): Objective of the agent.backstory (str): Backstory of the agent.- cache (bool): Whether the agent should use a cache for tool usage.+ cache (bool): Whether the agent participates in tool-result caching+ when a cache is enabled. The default (True) only permits+ participation — caching activates when the crew sets cache=True+ or the agent explicitly opts in with cache=True or a+ cache_handler; cache=False excludes the agent entirely.config (dict[str, Any] | None): Configuration for the agent.verbose (bool): Verbose mode for the Agent Execution.max_rpm (int | None): Maximum number of requests per minute for the agent execution.@@ -254,6 +258,7 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):_logger: Logger = PrivateAttr(default_factory=lambda: Logger(verbose=False))_rpm_controller: RPMController | None = PrivateAttr(default=None)_request_within_rpm_limit: SerializableCallable | None = PrivateAttr(default=None)+ _constructor_cache_opt_in: bool = PrivateAttr(default=False)_original_role: str | None = PrivateAttr(default=None)_original_goal: str | None = PrivateAttr(default=None)_original_backstory: str | None = PrivateAttr(default=None)@@ -267,7 +272,14 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):description="Configuration for the agent", default=None, exclude=True)cache: bool = Field(- default=True, description="Whether the agent should use a cache for tool usage."+ default=True,+ description=(+ "Whether the agent participates in tool-result caching when a "+ "cache is enabled. Caching itself is opt-in: it activates only "+ "when the crew sets cache=True or the agent explicitly opts in "+ "(cache=True or a cache_handler at construction). Set False to "+ "exclude this agent even when the crew enables caching."+ ),)verbose: bool = Field(default=False, description="Verbose mode for the Agent Execution"@@ -716,6 +728,19 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):copied_data = self.model_dump(exclude=exclude)copied_data = {k: v for k, v in copied_data.items() if v is not None}+ # Tool-result caching distinguishes "explicitly enabled" from the+ # field default via model_fields_set; don't let the dump turn the+ # default into an explicit opt-in on the copy. An agent that opted+ # in at construction via an explicit cache_handler (excluded from+ # the dump) must stay opted in — carry the consent as cache=True so+ # the copy wires its own fresh handler. A handler merely offered by+ # a crew at kickoff is runtime wiring, not consent, and must not+ # opt the copy in; _constructor_cache_opt_in is recorded before any+ # crew wiring can happen.+ if "cache" not in self.model_fields_set:+ copied_data.pop("cache", None)+ if self._constructor_cache_opt_in:+ copied_data["cache"] = Truereturn type(self)(**copied_data,llm=existing_llm,diff --git a/lib/crewai/src/crewai/crew.py b/lib/crewai/src/crewai/crew.pyindex 7d4a5107d..696d831c8 100644--- a/lib/crewai/src/crewai/crew.py+++ b/lib/crewai/src/crewai/crew.py@@ -168,8 +168,11 @@ class Crew(FlowTrackable, BaseModel):manager_agent: Custom agent that will be used as manager.memory: Whether the crew should use memory to store memories of it'sexecution.- cache: Whether the crew should use a cache to store the results of the- tools execution.+ cache: Whether to cache tool results for the crew's agents. Off by+ default; when enabled, repeated calls to the same tool with+ identical arguments reuse the first result without re-executing —+ avoid enabling for live-data or state-mutating tools unless they+ gate writes with a cache_function.function_calling_llm: The language model that will run the tool callingfor all the agents.process: The process flow that the crew will follow (e.g., sequential,@@ -216,7 +219,16 @@ class Crew(FlowTrackable, BaseModel):_kickoff_event_id: str | None = PrivateAttr(default=None)name: str | None = Field(default="crew")- cache: bool = Field(default=True)+ cache: bool = Field(+ default=False,+ description=(+ "Whether to cache tool results for the crew's agents. Opt-in: "+ "when enabled, repeated calls to the same tool with identical "+ "arguments return the first result without re-executing the "+ "tool — do not enable for live-data or state-mutating tools "+ "unless they set a cache_function that prevents caching."+ ),+ )tasks: list[Task] = Field(default_factory=list)agents: Annotated[list[BaseAgent],@@ -1507,6 +1519,11 @@ class Crew(FlowTrackable, BaseModel):)self.manager_agent = managermanager.crew = self+ # The manager is created outside the agents loop that offers the+ # crew's cache handler at validation time; offer it here so an+ # opted-in crew (cache=True) also dedupes the manager's tool calls.+ if self.cache:+ manager.set_cache_handler(self._cache_handler)def _get_execution_start_index(self, tasks: list[Task]) -> int | None:if self.checkpoint_kickoff_event_id is None:diff --git a/lib/crewai/tests/test_crew.py b/lib/crewai/tests/test_crew.pyindex 90d648711..0195112cb 100644--- a/lib/crewai/tests/test_crew.py+++ b/lib/crewai/tests/test_crew.py@@ -859,6 +859,7 @@ def test_cache_hitting_between_agents(researcher, writer, ceo):crew = Crew(agents=[ceo, researcher],tasks=tasks,+ cache=True,)with patch.object(CacheHandler, "read") as read:@@ -2246,7 +2247,9 @@ def test_tools_with_custom_caching():agent=writer2,)- crew = Crew(agents=[writer1, writer2], tasks=[task1, task2, task3, task4])+ crew = Crew(+ agents=[writer1, writer2], tasks=[task1, task2, task3, task4], cache=True+ )with patch.object(CacheHandler, "add", wraps=crew._cache_handler.adddiff --git a/lib/crewai/tests/test_tool_cache_default.py b/lib/crewai/tests/test_tool_cache_default.pynew file mode 100644index 000000000..7a503d269--- /dev/null+++ b/lib/crewai/tests/test_tool_cache_default.py@@ -0,0 +1,263 @@+# mypy: ignore-errors+"""Regression tests for EPD-180: tool-result caching used to be ON by default,+so an LLM calling the same tool with identical arguments twice in one run got+the first (possibly stale) result back without the tool executing — silently+wrong for live-data tools, and silently dropped actions for stateful tools.++Caching is now opt-in: ``Crew(cache=True)`` for crews, ``Agent(cache=True)``+(or an explicit ``cache_handler``) for standalone agents. The machinery —+including per-tool ``cache_function`` write gating — is unchanged once opted+in.++The end-to-end tests run fully offline: a fake OpenAI client scripts two+identical tool calls followed by a final answer, mirroring the EPD-180+clean-room repro.+"""++from openai.types.chat import ChatCompletion+from pydantic import BaseModel, Field++from crewai import LLM, Agent, Crew, Task+from crewai.agents.cache.cache_handler import CacheHandler+from crewai.tools import BaseTool+++class LookupArgs(BaseModel):+ city: str = Field(description="City to look up.")+++def make_live_tool():+ """A tool returning a different value on every real execution."""+ executions = []++ class LiveLookupTool(BaseTool):+ name: str = "live_lookup"+ description: str = "Returns a live (time-varying) reading for a city."+ args_schema: type[BaseModel] = LookupArgs+ # cache_function deliberately NOT set — exercising the default.++ def _run(self, city: str) -> str:+ executions.append(city)+ return f"reading #{len(executions)} for {city}"++ return LiveLookupTool(), executions+++def make_scripted_llm():+ """An offline LLM whose client scripts two identical tool calls."""++ def tool_call_response(call_id: str):+ return {+ "index": 0,+ "finish_reason": "tool_calls",+ "message": {+ "role": "assistant",+ "content": None,+ "tool_calls": [+ {+ "id": call_id,+ "type": "function",+ "function": {+ "name": "live_lookup",+ "arguments": '{"city": "paris"}',+ },+ }+ ],+ },+ }++ scripted = [+ tool_call_response("call_1"),+ tool_call_response("call_2"), # identical name+args, new id+ {+ "index": 0,+ "finish_reason": "stop",+ "message": {"role": "assistant", "content": "Final answer: done."},+ },+ ]++ class FakeCompletions:+ def __init__(self):+ self.n = 0++ def create(self, **params):+ choice = scripted[min(self.n, len(scripted) - 1)]+ self.n += 1+ return ChatCompletion.model_validate(+ {+ "id": f"chatcmpl-fake-{self.n}",+ "object": "chat.completion",+ "created": 1,+ "model": params.get("model", "gpt-4o"),+ "choices": [choice],+ "usage": {+ "prompt_tokens": 10,+ "completion_tokens": 5,+ "total_tokens": 15,+ },+ }+ )++ class FakeClient:+ def __init__(self):+ self.chat = type("Chat", (), {"completions": FakeCompletions()})()++ llm = LLM(model="openai/gpt-4o")+ llm._client = FakeClient()+ return llm+++def run_crew(**crew_kwargs):+ tool, executions = make_live_tool()+ agent = Agent(+ role="reader",+ goal="Look things up.",+ backstory="Test agent.",+ llm=make_scripted_llm(),+ tools=[tool],+ verbose=False,+ )+ task = Task(+ description="Look up paris twice and report.",+ expected_output="A report.",+ agent=agent,+ )+ crew = Crew(agents=[agent], tasks=[task], verbose=False, **crew_kwargs)+ crew.kickoff()+ return executions+++class TestToolCachingIsOptIn:+ def test_default_reexecutes_identical_tool_calls(self):+ """EPD-180: with no opt-in, both identical calls must really execute."""+ executions = run_crew()+ assert len(executions) == 2++ def test_crew_cache_true_dedupes_identical_tool_calls(self):+ """Opting in via Crew(cache=True) restores the dedup behavior."""+ executions = run_crew(cache=True)+ assert len(executions) == 1+++class TestAgentCacheWiring:+ def _agent(self, **kwargs) -> Agent:+ return Agent(+ role="reader",+ goal="Look things up.",+ backstory="Test agent.",+ **kwargs,+ )++ def test_standalone_agent_has_no_cache_by_default(self):+ agent = self._agent()+ assert agent.tools_handler.cache is None+ assert agent.cache_handler is None++ def test_standalone_agent_explicit_cache_true_opts_in(self):+ agent = self._agent(cache=True)+ assert agent.tools_handler.cache is not None+ assert agent.cache_handler is not None++ def test_standalone_agent_explicit_cache_handler_opts_in(self):+ handler = CacheHandler()+ agent = self._agent(cache_handler=handler)+ assert agent.tools_handler.cache is handler++ def test_explicit_cache_false_stays_off_even_with_handler(self):+ agent = self._agent(cache=False, cache_handler=CacheHandler())+ assert agent.tools_handler.cache is None++ def test_agents_accept_a_crew_offered_handler_by_default(self):+ """``Crew(cache=True)`` offers its handler via set_cache_handler at+ kickoff; agents that didn't explicitly opt out must accept it."""+ agent = self._agent()+ assert agent.tools_handler.cache is None++ handler = CacheHandler()+ agent.set_cache_handler(handler)+ assert agent.tools_handler.cache is handler++ def test_agents_that_opted_out_refuse_a_crew_offered_handler(self):+ agent = self._agent(cache=False)+ agent.set_cache_handler(CacheHandler())+ assert agent.tools_handler.cache is None++ def test_copy_of_default_agent_does_not_opt_in(self):+ """copy() rebuilds from model_dump(), which includes the field+ default cache=True — that must not read as an explicit opt-in on+ the copy (Bugbot review finding on the original PR)."""+ copied = self._agent().copy()+ assert copied.tools_handler.cache is None+ assert copied.cache_handler is None++ def test_copy_of_opted_in_agent_stays_opted_in(self):+ copied = self._agent(cache=True).copy()+ assert copied.tools_handler.cache is not None++ def test_copy_of_handler_opted_in_agent_stays_opted_in(self):+ """An explicit cache_handler is an opt-in too; copy() excludes the+ handler itself, but the consent must survive — the copy wires its+ own fresh handler (Bugbot review finding on the original PR)."""+ source = self._agent(cache_handler=CacheHandler())+ copied = source.copy()+ assert copied.tools_handler.cache is not None+ assert copied.tools_handler.cache is not source.tools_handler.cache++ def test_copy_of_explicit_cache_false_with_handler_stays_off(self):+ copied = self._agent(cache=False, cache_handler=CacheHandler()).copy()+ assert copied.tools_handler.cache is None++ def test_copy_of_crew_wired_agent_does_not_opt_in(self):+ """A handler offered by a crew at kickoff (set_cache_handler) is+ runtime wiring, not construction-time consent — copies of such+ agents must not become standalone cachers (Bugbot review finding+ on the original PR)."""+ agent = self._agent()+ agent.set_cache_handler(CacheHandler()) # what Crew(cache=True) does+ assert agent.tools_handler.cache is not None++ copied = agent.copy()+ assert copied.tools_handler.cache is None+ assert copied.cache_handler is None+++class TestHierarchicalManagerCacheWiring:+ """The auto-created hierarchical manager is built outside the agents+ loop that offers the crew's cache handler; an opted-in crew must wire+ the manager too (Bugbot review finding on the original PR)."""++ def _crew(self, **crew_kwargs) -> Crew:+ from crewai.process import Process++ agent = Agent(role="worker", goal="Do work.", backstory="Test agent.")+ task = Task(description="Do the work.", expected_output="Done.")+ return Crew(+ agents=[agent],+ tasks=[task],+ process=Process.hierarchical,+ manager_llm="gpt-4o",+ **crew_kwargs,+ )++ def test_manager_gets_crew_handler_when_cache_enabled(self):+ crew = self._crew(cache=True)+ crew._create_manager_agent()+ assert crew.manager_agent.tools_handler.cache is crew._cache_handler++ def test_manager_has_no_cache_when_crew_did_not_opt_in(self):+ crew = self._crew()+ crew._create_manager_agent()+ assert crew.manager_agent.tools_handler.cache is None++ def test_user_provided_manager_with_cache_false_stays_excluded(self):+ manager = Agent(+ role="manager",+ goal="Manage.",+ backstory="Test manager.",+ cache=False,+ allow_delegation=True,+ )+ crew = self._crew(cache=True)+ crew.manager_agent = manager+ crew._create_manager_agent()+ assert manager.tools_handler.cache is None