Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
fix: skip interception hooks on crewai-internal flows (#7079)
Lucas Gomide3df34d91690c
diff --git a/lib/crewai/src/crewai/experimental/agent_executor.py b/lib/crewai/src/crewai/experimental/agent_executor.pyindex d2a0436fa..45fffa1e4 100644--- a/lib/crewai/src/crewai/experimental/agent_executor.py+++ b/lib/crewai/src/crewai/experimental/agent_executor.py@@ -55,6 +55,7 @@ from crewai.events.types.tool_usage_events import (ToolUsageStartedEvent,)from crewai.flow.flow import Flow, listen, or_, router, start+from crewai.flow.flow_context import current_flow_idfrom crewai.flow.types import FlowMethodNamefrom crewai.hooks.llm_hooks import (get_after_llm_call_hooks,@@ -244,6 +245,20 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):self._flow_post_init()return self+ def _owns_execution_boundary(self) -> bool:+ """Only a standalone ``Agent.kickoff()`` is a run of its own.++ Crew-bound, the crew owns the run. Nested in a caller's flow, that flow+ does: boundaries belong to the root, and the active flow id is the+ caller's rather than this executor's.+ """+ if self.crew is not None:+ return False+ # Also set by context restores (threads, enterprise request headers),+ # where a foreign id likewise means a run above this one.+ active_flow_id = current_flow_id.get()+ return active_flow_id is None or active_flow_id == self.flow_id+def _check_native_tool_support(self) -> bool:"""Check if LLM supports native function calling."""return check_native_tool_support(self.llm, self.original_tools)diff --git a/lib/crewai/src/crewai/flow/runtime/__init__.py b/lib/crewai/src/crewai/flow/runtime/__init__.pyindex 07e53de19..01f645e2e 100644--- a/lib/crewai/src/crewai/flow/runtime/__init__.py+++ b/lib/crewai/src/crewai/flow/runtime/__init__.py@@ -139,6 +139,8 @@ if TYPE_CHECKING:from crewai_files import FileInputfrom crewai.context import ExecutionContext+ from crewai.hooks.contexts import InterceptionContext+ from crewai.hooks.dispatch import InterceptionPointfrom crewai.llms.base_llm import BaseLLMfrom crewai.flow.visualization import build_flow_structure, render_interactive@@ -1282,7 +1284,9 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):instance._is_execution_resuming = True# Seed the match id so the resume-phase listener filters its own# LLM events (which run with `current_flow_id == instance.flow_id`)- # instead of dropping or absorbing unrelated ones.+ # instead of dropping or absorbing unrelated ones. Must stay+ # `instance.flow_id`: resume forces `current_flow_id` to this value and+ # `_owns_execution_boundary` compares the two.instance._flow_match_id = instance.flow_idreturn instance@@ -1587,20 +1591,23 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):)from crewai.hooks.contexts import ExecutionEndContext, OutputContext- from crewai.hooks.dispatch import InterceptionPoint, dispatch+ from crewai.hooks.dispatch import InterceptionPointoutput_ctx = OutputContext(flow=self, output=final_result, payload=final_result)- dispatch(InterceptionPoint.OUTPUT, output_ctx)+ self._dispatch_interception(InterceptionPoint.OUTPUT, output_ctx)final_result = output_ctx.payloadend_ctx = ExecutionEndContext(flow=self, output=final_result, payload=final_result)# Flag set before dispatching so an EXECUTION_END hook that raises- # HookAborted does not trigger a second (failure) dispatch upstream.- if hook_state is not None:+ # HookAborted does not trigger a second (failure) dispatch upstream. A+ # skipped dispatch leaves it false, matching the kickoff path.+ if hook_state is not None and not self._skip_interception(+ InterceptionPoint.EXECUTION_END+ ):hook_state["end_dispatched"] = True- dispatch(InterceptionPoint.EXECUTION_END, end_ctx)+ self._dispatch_interception(InterceptionPoint.EXECUTION_END, end_ctx)final_result = end_ctx.payloadif self._event_futures:@@ -2217,10 +2224,9 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):ExecutionEndContext,ExecutionStartContext,InputContext,- InterceptionContext,OutputContext,)- from crewai.hooks.dispatch import HookAborted, InterceptionPoint, dispatch+ from crewai.hooks.dispatch import HookAborted, InterceptionPoint# ``inputs`` aliases the same object as ``payload`` (not a fresh# ``{}`` from ``or``) so in-place edits survive read-back.@@ -2230,8 +2236,9 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):inputs=inputs if inputs is not None else {},payload=inputs,)- dispatch(InterceptionPoint.EXECUTION_START, boundary_ctx)- execution_start_dispatched = True+ execution_start_dispatched = self._dispatch_interception(+ InterceptionPoint.EXECUTION_START, boundary_ctx+ )inputs = boundary_ctx.payloadboundary_ctx = InputContext(@@ -2239,7 +2246,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):inputs=inputs if inputs is not None else {},payload=inputs,)- dispatch(InterceptionPoint.INPUT, boundary_ctx)+ self._dispatch_interception(InterceptionPoint.INPUT, boundary_ctx)inputs = boundary_ctx.payloadexcept HookAborted:# The deny surfaces as started -> failed. Read the payload back@@ -2446,7 +2453,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):output_ctx = OutputContext(flow=self, output=final_output, payload=final_output)- dispatch(InterceptionPoint.OUTPUT, output_ctx)+ self._dispatch_interception(InterceptionPoint.OUTPUT, output_ctx)final_output = output_ctx.payload# EXECUTION_END runs before FlowFinishedEvent so a HookAborted@@ -2456,9 +2463,13 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):flow=self, output=final_output, payload=final_output)# Flag set before dispatching so an EXECUTION_END hook that raises- # HookAborted does not trigger a second (failure) dispatch below.- execution_end_dispatched = True- dispatch(InterceptionPoint.EXECUTION_END, end_ctx)+ # HookAborted does not trigger a second (failure) dispatch below. A+ # skipped dispatch leaves it false, so it means the same as+ # ``execution_start_dispatched``.+ execution_end_dispatched = not self._skip_interception(+ InterceptionPoint.EXECUTION_END+ )+ self._dispatch_interception(InterceptionPoint.EXECUTION_END, end_ctx)final_output = end_ctx.payloadif self._event_futures:@@ -2549,6 +2560,46 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):detach(flow_token)crewai_event_bus._exit_runtime_scope(runtime_scope)+ def _skip_interception(self, point: InterceptionPoint) -> bool:+ """Whether ``point`` must not be dispatched for this flow.++ Per point rather than per flow: an internal flow that is itself the+ whole run still owns that run's execution boundary, even though its+ methods are never a caller's steps.+ """+ if not type(self).is_crewai_internal:+ return False+ from crewai.hooks.dispatch import EXECUTION_BOUNDARY_POINTS++ return (+ point not in EXECUTION_BOUNDARY_POINTS+ or not self._owns_execution_boundary()+ )++ def _owns_execution_boundary(self) -> bool:+ """Whether this flow is the run the caller asked for.++ A caller's flow always is. Internal machinery is not, unless it is the+ entry point the caller invoked (``Agent.kickoff()``), which the classes+ that can be one override; the rest need nothing.+ """+ return not type(self).is_crewai_internal++ def _dispatch_interception(+ self, point: InterceptionPoint, ctx: InterceptionContext+ ) -> bool:+ """Dispatch ``point`` unless this flow must not expose it.++ Returns whether the dispatch happened, so callers can keep the+ EXECUTION_START/EXECUTION_END pairing honest on a skipped flow.+ """+ if self._skip_interception(point):+ return False+ from crewai.hooks.dispatch import dispatch++ dispatch(point, ctx)+ return True+def _dispatch_execution_end_failure(self, error: BaseException) -> None:"""Dispatch EXECUTION_END with status="failed" for an execution that raised.@@ -2558,10 +2609,10 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):exception propagates unchanged."""from crewai.hooks.contexts import ExecutionEndContext- from crewai.hooks.dispatch import InterceptionPoint, dispatch+ from crewai.hooks.dispatch import InterceptionPointtry:- dispatch(+ self._dispatch_interception(InterceptionPoint.EXECUTION_END,ExecutionEndContext(flow=self, status="failed", error=error),)@@ -2872,35 +2923,38 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):self._event_futures.append(future)from crewai.hooks.contexts import StepContext- from crewai.hooks.dispatch import InterceptionPoint, dispatch-- pre_step_ctx = StepContext(- kind="flow_method",- step_name=str(method_name),- flow=self,- payload=dumped_params,- )- dispatch(InterceptionPoint.PRE_STEP, pre_step_ctx)-- # Apply hook edits/replacement of the step params back onto the- # call. ``dumped_params`` maps positional args to ``_0, _1, ...``- # keys and keeps kwargs by name, so reverse that mapping here.- updated_params = pre_step_ctx.payload- if isinstance(updated_params, dict):- positional = sorted(- (- k- for k in updated_params- if k.startswith("_") and k[1:].isdigit()- ),- key=lambda k: int(k[1:]),+ from crewai.hooks.dispatch import InterceptionPoint++ # Guarded here as well as inside the dispatch: a skipped flow must+ # not pay for building the context or reversing the param mapping.+ if not self._skip_interception(InterceptionPoint.PRE_STEP):+ pre_step_ctx = StepContext(+ kind="flow_method",+ step_name=str(method_name),+ flow=self,+ payload=dumped_params,)- args = tuple(updated_params[k] for k in positional)- kwargs = {- k: v- for k, v in updated_params.items()- if not (k.startswith("_") and k[1:].isdigit())- }+ self._dispatch_interception(InterceptionPoint.PRE_STEP, pre_step_ctx)++ # Apply hook edits/replacement of the step params back onto the+ # call. ``dumped_params`` maps positional args to ``_0, _1, ...``+ # keys and keeps kwargs by name, so reverse that mapping here.+ updated_params = pre_step_ctx.payload+ if isinstance(updated_params, dict):+ positional = sorted(+ (+ k+ for k in updated_params+ if k.startswith("_") and k[1:].isdigit()+ ),+ key=lambda k: int(k[1:]),+ )+ args = tuple(updated_params[k] for k in positional)+ kwargs = {+ k: v+ for k, v in updated_params.items()+ if not (k.startswith("_") and k[1:].isdigit())+ }# Set method name in context so ask() can read it without# stack inspection. Must happen before copy_context() so the@@ -2929,15 +2983,16 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):method_name, method_definition.human_feedback, result)- post_step_ctx = StepContext(- kind="flow_method",- step_name=str(method_name),- flow=self,- output=result,- payload=result,- )- dispatch(InterceptionPoint.POST_STEP, post_step_ctx)- result = post_step_ctx.payload+ if not self._skip_interception(InterceptionPoint.POST_STEP):+ post_step_ctx = StepContext(+ kind="flow_method",+ step_name=str(method_name),+ flow=self,+ output=result,+ payload=result,+ )+ self._dispatch_interception(InterceptionPoint.POST_STEP, post_step_ctx)+ result = post_step_ctx.payloadself._method_outputs.append({"method": str(method_name), "output": result})diff --git a/lib/crewai/src/crewai/hooks/__init__.py b/lib/crewai/src/crewai/hooks/__init__.pyindex 16c6fe0fc..79e90ed97 100644--- a/lib/crewai/src/crewai/hooks/__init__.py+++ b/lib/crewai/src/crewai/hooks/__init__.py@@ -7,6 +7,7 @@ from crewai.hooks.decorators import (before_tool_call,)from crewai.hooks.dispatch import (+ EXECUTION_BOUNDARY_POINTS,HookAborted,InterceptionPoint,clear as clear_hooks,@@ -85,6 +86,7 @@ def clear_all_global_hooks() -> dict[str, tuple[int, int]]:__all__ = [+ "EXECUTION_BOUNDARY_POINTS","HookAborted","InterceptionPoint","LLMCallHookContext",diff --git a/lib/crewai/src/crewai/hooks/dispatch.py b/lib/crewai/src/crewai/hooks/dispatch.pyindex 28aad5500..fd692c900 100644--- a/lib/crewai/src/crewai/hooks/dispatch.py+++ b/lib/crewai/src/crewai/hooks/dispatch.py@@ -61,6 +61,17 @@ class InterceptionPoint(str, Enum):POST_STEP = "post_step"+EXECUTION_BOUNDARY_POINTS: frozenset[InterceptionPoint] = frozenset(+ {+ InterceptionPoint.EXECUTION_START,+ InterceptionPoint.INPUT,+ InterceptionPoint.OUTPUT,+ InterceptionPoint.EXECUTION_END,+ }+)+"""The points that open and close a run, as opposed to steps within it."""++class HookAborted(Exception): # noqa: N818 - public contract name from OSS-86"""Raised by a hook (or a legacy adapter) to abort the intercepted operation.diff --git a/lib/crewai/tests/hooks/test_interception_conformance.py b/lib/crewai/tests/hooks/test_interception_conformance.pyindex f171c3801..f60852620 100644--- a/lib/crewai/tests/hooks/test_interception_conformance.py+++ b/lib/crewai/tests/hooks/test_interception_conformance.py@@ -8,6 +8,7 @@ sees a well-shaped payload, an in-place/returned modification is honored, and afrom __future__ import annotationsimport asyncio+from typing import ClassVarfrom unittest.mock import patchfrom crewai.agent import Agent@@ -20,12 +21,15 @@ from crewai.events.types.flow_events import (FlowStartedEvent,)from crewai.flow.flow import Flow, listen, start+from crewai.flow.flow_context import current_flow_idfrom crewai.hooks.dispatch import (HookAborted,InterceptionPoint,clear_all,on,)+from crewai.llm import LLM+from crewai.memory.recall_flow import RecallFlowfrom crewai.task import Taskimport pytest@@ -47,6 +51,22 @@ class _SimpleFlow(Flow):return "flow-result"+class _InternalFlow(Flow):+ is_crewai_internal: ClassVar[bool] = True++ @start()+ def begin(self):+ return "ok"+++class _QuietFlow(Flow):+ suppress_flow_events: bool = True++ @start()+ def begin(self):+ return "ok"++class _FailingFlow(Flow):@start()def begin(self):@@ -130,6 +150,52 @@ class TestFlowExecutionBoundaries:_SimpleFlow().kickoff()assert exc.value.reason == "not allowed"+ def test_internal_flow_does_not_fire_boundary_hooks(self):+ fired: list[str] = []++ for point in (+ InterceptionPoint.EXECUTION_START,+ InterceptionPoint.INPUT,+ InterceptionPoint.OUTPUT,+ InterceptionPoint.EXECUTION_END,+ ):++ @on(point)+ def _probe(ctx, _point=point):+ fired.append(_point.value)++ assert _InternalFlow().kickoff(inputs={"query": "x"}) == "ok"+ assert fired == []++ def test_internal_flow_ignores_input_hook_abort(self):+ @on(InterceptionPoint.INPUT)+ def block(ctx):+ raise HookAborted(reason="blocked", source="policy")++ assert _InternalFlow().kickoff(inputs={"query": "x"}) == "ok"++ def test_quiet_user_flow_still_fires_boundary_hooks(self):+ fired: list[str] = []++ for point in (+ InterceptionPoint.EXECUTION_START,+ InterceptionPoint.INPUT,+ InterceptionPoint.OUTPUT,+ InterceptionPoint.EXECUTION_END,+ ):++ @on(point)+ def _probe(ctx, _point=point):+ fired.append(_point.value)++ assert _QuietFlow().kickoff(inputs={"seed": 1}) == "ok"+ assert fired == [+ "execution_start",+ "input",+ "output",+ "execution_end",+ ]+class TestFlowStepPoints:"""pre_step / post_step for flow methods (kind=flow_method)."""@@ -161,6 +227,182 @@ class TestFlowStepPoints:assert _SimpleFlow().kickoff() == "rewritten"+ def test_internal_flow_does_not_fire_step_hooks(self):+ fired: list[str] = []++ @on(InterceptionPoint.PRE_STEP)+ def pre(ctx):+ fired.append(f"pre:{ctx.step_name}")++ @on(InterceptionPoint.POST_STEP)+ def post(ctx):+ fired.append(f"post:{ctx.step_name}")++ assert _InternalFlow().kickoff() == "ok"+ assert fired == []++ def test_internal_flow_ignores_step_hook_abort(self):+ @on(InterceptionPoint.PRE_STEP)+ def block(ctx):+ raise HookAborted(reason="blocked", source="policy")++ assert _InternalFlow().kickoff() == "ok"++ def test_quiet_user_flow_still_fires_step_hooks(self):+ fired: list[str] = []++ @on(InterceptionPoint.PRE_STEP)+ def pre(ctx):+ fired.append(f"pre:{ctx.step_name}")++ @on(InterceptionPoint.POST_STEP)+ def post(ctx):+ fired.append(f"post:{ctx.step_name}")++ assert _QuietFlow().kickoff() == "ok"+ assert fired == ["pre:begin", "post:begin"]+++class TestCrewaiInternalFlows:+ """The agent executor runs for real here.++ Patching ``Agent.execute_task`` skips the very flow whose dispatches used+ to leak into the caller's run, so only a real executor proves the skip.+ """++ _POINTS = (+ InterceptionPoint.EXECUTION_START,+ InterceptionPoint.INPUT,+ InterceptionPoint.PRE_STEP,+ InterceptionPoint.POST_STEP,+ InterceptionPoint.OUTPUT,+ InterceptionPoint.EXECUTION_END,+ )++ @staticmethod+ def _agent() -> Agent:+ return Agent(+ role="Writer",+ goal="Write",+ backstory="Writes things.",+ llm=LLM(model="gpt-4o-mini"),+ )++ @classmethod+ def _record(cls) -> list[tuple[str, str | None]]:+ fired: list[tuple[str, str | None]] = []+ for point in cls._POINTS:++ @on(point)+ def _probe(ctx, _point=point):+ fired.append((_point.value, getattr(ctx, "kind", None)))++ return fired++ def test_crew_run_dispatches_only_the_crews_own_points(self):+ fired = self._record()+ agent = self._agent()+ task = Task(+ description="Write something", expected_output="Some text", agent=agent+ )++ with patch.object(type(agent.llm), "call", return_value="Final Answer: done"):+ Crew(agents=[agent], tasks=[task], verbose=False).kickoff()++ assert fired == [+ ("execution_start", None),+ ("input", None),+ ("pre_step", "task"),+ ("post_step", "task"),+ ("output", None),+ ("execution_end", None),+ ]++ def test_standalone_agent_kickoff_keeps_its_execution_boundary(self):+ fired = self._record()+ agent = self._agent()++ with patch.object(type(agent.llm), "call", return_value="Final Answer: done"):+ agent.kickoff("write something")++ assert fired == [+ ("execution_start", None),+ ("input", None),+ ("output", None),+ ("execution_end", None),+ ]++ def test_agent_kickoff_inside_a_flow_leaves_the_boundary_to_the_flow(self):+ fired = self._record()+ agent = self._agent()++ class _AgentFlow(Flow):+ @start()+ def run_agent(self):+ agent.kickoff("write something")+ return "flow-result"++ with patch.object(type(agent.llm), "call", return_value="Final Answer: done"):+ assert _AgentFlow().kickoff() == "flow-result"++ assert fired == [+ ("execution_start", None),+ ("input", None),+ ("pre_step", "flow_method"),+ ("post_step", "flow_method"),+ ("output", None),+ ("execution_end", None),+ ]++ def test_the_memory_recall_flow_dispatches_nothing(self):+ fired = self._record()++ class _Storage:+ def list_scopes(self, _prefix):+ return ["/"]++ def search(self, *_args, **_kwargs):+ return []++ flow = RecallFlow(+ storage=_Storage(),+ llm=None,+ embedder=lambda texts: [[0.1] for _ in texts],+ )++ assert flow.kickoff(inputs={"query": "anything"}) == []+ assert fired == []++ def test_a_restored_outer_flow_id_keeps_the_agent_out_of_the_boundary(self):+ fired = self._record()+ agent = self._agent()++ token = current_flow_id.set("run-owned-by-another-process")+ try:+ with patch.object(+ type(agent.llm), "call", return_value="Final Answer: done"+ ):+ agent.kickoff("write something")+ finally:+ current_flow_id.reset(token)++ assert fired == []++ def test_standalone_agent_kickoff_is_blockable(self):+ @on(InterceptionPoint.EXECUTION_START)+ def block(ctx):+ raise HookAborted(reason="not allowed", source="policy")++ agent = self._agent()++ with patch.object(+ type(agent.llm), "call", return_value="Final Answer: done"+ ) as call:+ with pytest.raises(HookAborted):+ agent.kickoff("write something")++ call.assert_not_called()+class TestTaskStepPoints:"""pre_step / post_step for task execution (kind=task)."""diff --git a/lib/crewai/tests/utilities/test_events.py b/lib/crewai/tests/utilities/test_events.pyindex 77a4a6578..e2f99a54c 100644--- a/lib/crewai/tests/utilities/test_events.py+++ b/lib/crewai/tests/utilities/test_events.py@@ -1295,6 +1295,16 @@ def test_infrastructure_flows_suppress_flow_events_by_default():assert flow.suppress_flow_events is True+def test_infrastructure_flows_are_marked_internal():+ from crewai.experimental.agent_executor import AgentExecutor+ from crewai.memory.encoding_flow import EncodingFlow+ from crewai.memory.recall_flow import RecallFlow++ assert AgentExecutor.is_crewai_internal is True+ assert EncodingFlow.is_crewai_internal is True+ assert RecallFlow.is_crewai_internal is True++@pytest.mark.vcr()def test_llm_emits_call_started_event():started_events: list[LLMCallStartedEvent] = []