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.

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.py
index 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_id
from crewai.flow.types import FlowMethodName
from 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__.py
index 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 FileInput
from crewai.context import ExecutionContext
+ from crewai.hooks.contexts import InterceptionContext
+ from crewai.hooks.dispatch import InterceptionPoint
from crewai.llms.base_llm import BaseLLM
from 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_id
return 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 InterceptionPoint
output_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.payload
end_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.payload
if 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.payload
boundary_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.payload
except 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.payload
if 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 InterceptionPoint
try:
- 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.payload
self._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__.py
index 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.py
index 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.py
index 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 a
from __future__ import annotations
import asyncio
+from typing import ClassVar
from unittest.mock import patch
from 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_id
from crewai.hooks.dispatch import (
HookAborted,
InterceptionPoint,
clear_all,
on,
)
+from crewai.llm import LLM
+from crewai.memory.recall_flow import RecallFlow
from crewai.task import Task
import 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.py
index 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] = []