Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat: wire execution-boundary interception points (#6517)
Lucas Gomidea194f3867aea
diff --git a/lib/crewai/src/crewai/crew.py b/lib/crewai/src/crewai/crew.pyindex 696d831c8..686b08cc4 100644--- a/lib/crewai/src/crewai/crew.py+++ b/lib/crewai/src/crewai/crew.py@@ -1906,6 +1906,28 @@ class Crew(FlowTrackable, BaseModel):final_string_output = final_task_output.rawself._finish_execution(final_string_output)self.token_usage = self.calculate_usage_metrics()++ from crewai.hooks.contexts import ExecutionEndContext, OutputContext+ from crewai.hooks.dispatch import InterceptionPoint, dispatch++ crew_output = CrewOutput(+ raw=final_task_output.raw,+ pydantic=final_task_output.pydantic,+ json_dict=final_task_output.json_dict,+ tasks_output=task_outputs,+ token_usage=self.token_usage,+ )++ output_ctx = OutputContext(crew=self, output=crew_output, payload=crew_output)+ dispatch(InterceptionPoint.OUTPUT, output_ctx)+ crew_output = cast(CrewOutput, output_ctx.payload)++ end_ctx = ExecutionEndContext(+ crew=self, output=crew_output, payload=crew_output+ )+ dispatch(InterceptionPoint.EXECUTION_END, end_ctx)+ crew_output = cast(CrewOutput, end_ctx.payload)+# Ensure background memory saves finish (and emit their# completed/failed events) before the kickoff-completed event below# triggers listener teardown/finalization.@@ -1924,13 +1946,7 @@ class Crew(FlowTrackable, BaseModel):# Finalization is handled by trace listener (always initialized)# The batch manager checks contextvar to determine if tracing is enabled- return CrewOutput(- raw=final_task_output.raw,- pydantic=final_task_output.pydantic,- json_dict=final_task_output.json_dict,- tasks_output=task_outputs,- token_usage=self.token_usage,- )+ return crew_outputdef _process_async_tasks(self,diff --git a/lib/crewai/src/crewai/crews/utils.py b/lib/crewai/src/crewai/crews/utils.pyindex 6faa0e8c2..bfac589ec 100644--- a/lib/crewai/src/crewai/crews/utils.py+++ b/lib/crewai/src/crewai/crews/utils.py@@ -278,6 +278,9 @@ def prepare_kickoff(reset_emission_counter()reset_last_event_id()+ from crewai.hooks.contexts import ExecutionStartContext, InputContext+ from crewai.hooks.dispatch import InterceptionPoint, dispatch+normalized: dict[str, Any] | None = Noneif inputs is not None:if not isinstance(inputs, Mapping):@@ -286,11 +289,30 @@ def prepare_kickoff()normalized = dict(inputs)+ # ``inputs`` aliases the same object as ``payload`` (not a fresh ``{}`` from+ # ``or``) so in-place edits to either survive read-back, per the context+ # contract. ``None`` inputs are preserved rather than coerced to ``{}``.+ start_ctx = ExecutionStartContext(+ crew=crew,+ inputs=normalized if normalized is not None else {},+ payload=normalized,+ )+ dispatch(InterceptionPoint.EXECUTION_START, start_ctx)+ normalized = start_ctx.payload+for before_callback in crew.before_kickoff_callbacks:if normalized is None:normalized = {}normalized = before_callback(normalized)+ input_ctx = InputContext(+ crew=crew,+ inputs=normalized if normalized is not None else {},+ payload=normalized,+ )+ dispatch(InterceptionPoint.INPUT, input_ctx)+ normalized = input_ctx.payload+if resuming and crew._kickoff_event_id:if crew.verbose:from crewai.events.utils.console_formatter import ConsoleFormatterdiff --git a/lib/crewai/src/crewai/flow/runtime/__init__.py b/lib/crewai/src/crewai/flow/runtime/__init__.pyindex a6c73e697..6733c4645 100644--- a/lib/crewai/src/crewai/flow/runtime/__init__.py+++ b/lib/crewai/src/crewai/flow/runtime/__init__.py@@ -1476,6 +1476,19 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):else (resumed_method_output if emit else result))+ from crewai.hooks.contexts import ExecutionEndContext, OutputContext+ from crewai.hooks.dispatch import InterceptionPoint, dispatch++ output_ctx = OutputContext(flow=self, output=final_result, payload=final_result)+ dispatch(InterceptionPoint.OUTPUT, output_ctx)+ final_result = output_ctx.payload++ end_ctx = ExecutionEndContext(+ flow=self, output=final_result, payload=final_result+ )+ dispatch(InterceptionPoint.EXECUTION_END, end_ctx)+ final_result = end_ctx.payload+if self._event_futures:await asyncio.gather(*[@@ -2037,6 +2050,9 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):flow_name_token = Noneflow_defer_trace_finalization_token = Nonerequest_id_token = None+ # Re-published after the INPUT hook so trigger-payload injection reads+ # the hook-rewritten inputs rather than the pre-hook baggage above.+ flow_inputs_token = Noneif current_flow_id.get() is None:flow_id_token = current_flow_id.set(self.flow_id)flow_name_token = current_flow_name.set(@@ -2062,6 +2078,37 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):self._attach_usage_aggregation_listener()try:+ from crewai.hooks.contexts import (+ ExecutionEndContext,+ ExecutionStartContext,+ InputContext,+ OutputContext,+ )+ from crewai.hooks.dispatch import InterceptionPoint, dispatch++ # ``inputs`` aliases the same object as ``payload`` (not a fresh+ # ``{}`` from ``or``) so in-place edits survive read-back.+ start_ctx = ExecutionStartContext(+ flow=self,+ inputs=inputs if inputs is not None else {},+ payload=inputs,+ )+ dispatch(InterceptionPoint.EXECUTION_START, start_ctx)+ inputs = start_ctx.payload++ input_ctx = InputContext(+ flow=self,+ inputs=inputs if inputs is not None else {},+ payload=inputs,+ )+ dispatch(InterceptionPoint.INPUT, input_ctx)+ inputs = input_ctx.payload++ # Publish the resolved inputs so trigger-payload injection and other+ # baggage readers observe hook rewrites (the baggage set before the+ # hooks carried the pre-hook inputs).+ flow_inputs_token = attach(baggage.set_baggage("flow_inputs", inputs or {}))+# Reset flow state for fresh execution unless restoring from persistenceis_restoring = (inputs and "id" in inputs and self.persistence is not None@@ -2297,6 +2344,21 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):method_outputs = self.method_outputsfinal_output = method_outputs[-1] if method_outputs else None+ output_ctx = OutputContext(+ flow=self, output=final_output, payload=final_output+ )+ dispatch(InterceptionPoint.OUTPUT, output_ctx)+ final_output = output_ctx.payload++ # EXECUTION_END runs before FlowFinishedEvent so a HookAborted+ # prevents a spurious finished signal and payload replacement is+ # honored on the emitted result and the returned value.+ end_ctx = ExecutionEndContext(+ flow=self, output=final_output, payload=final_output+ )+ dispatch(InterceptionPoint.EXECUTION_END, end_ctx)+ final_output = end_ctx.payload+if self._event_futures:await asyncio.gather(*[asyncio.wrap_future(f) for f in self._event_futures]@@ -2370,6 +2432,8 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):current_flow_name.reset(flow_name_token)if flow_id_token is not None:current_flow_id.reset(flow_id_token)+ if flow_inputs_token is not None:+ detach(flow_inputs_token)detach(flow_token)crewai_event_bus._exit_runtime_scope(runtime_scope)diff --git a/lib/crewai/src/crewai/hooks/contexts.py b/lib/crewai/src/crewai/hooks/contexts.pynew file mode 100644index 000000000..d718903b1--- /dev/null+++ b/lib/crewai/src/crewai/hooks/contexts.py@@ -0,0 +1,58 @@+"""Typed contexts for the interception points wired in phases 2-5.++Each context is a dataclass whose fields are nullable and defaulted, so a field+that is not meaningful for a given runtime (e.g. ``agent_role`` inside a flow)+is simply ``None`` rather than an error. Every context exposes a ``payload``+field: the interceptable value a hook may mutate in place or replace by+returning a new value.++The legacy ``pre/post_model_call`` and ``pre/post_tool_call`` points keep using+:class:`~crewai.hooks.llm_hooks.LLMCallHookContext` and+:class:`~crewai.hooks.tool_hooks.ToolCallHookContext` for backwards+compatibility; they are intentionally not redefined here.+"""++from __future__ import annotations++from dataclasses import dataclass, field+from typing import Any+++@dataclass+class InterceptionContext:+ """Base context shared by the framework-native interception points."""++ payload: Any = None+ agent: Any = None+ agent_role: str | None = None+ task: Any = None+ crew: Any = None+ flow: Any = None+++@dataclass+class ExecutionStartContext(InterceptionContext):+ """``execution_start``: a crew or flow is about to begin. ``payload`` = inputs."""++ inputs: dict[str, Any] = field(default_factory=dict)+++@dataclass+class InputContext(InterceptionContext):+ """``input``: resolved inputs for an execution. ``payload`` = inputs."""++ inputs: dict[str, Any] = field(default_factory=dict)+++@dataclass+class OutputContext(InterceptionContext):+ """``output``: final result of a crew or flow. ``payload`` = the output object."""++ output: Any = None+++@dataclass+class ExecutionEndContext(InterceptionContext):+ """``execution_end``: a crew or flow has finished. ``payload`` = the output object."""++ output: Any = Nonediff --git a/lib/crewai/src/crewai/hooks/dispatch.py b/lib/crewai/src/crewai/hooks/dispatch.pyindex 2822c73dd..095484220 100644--- a/lib/crewai/src/crewai/hooks/dispatch.py+++ b/lib/crewai/src/crewai/hooks/dispatch.py@@ -41,11 +41,15 @@ class InterceptionPoint(str, Enum):"""Interception points wired by this layer.New points are introduced alongside the seams that dispatch them, so the- enum only ever lists points with a live consumer. This layer ships the- model- and tool-call boundaries, which back the legacy- ``before/after_llm_call`` and ``before/after_tool_call`` hooks.+ enum only ever lists points with a live consumer."""+ # Execution-level boundaries+ EXECUTION_START = "execution_start"+ INPUT = "input"+ OUTPUT = "output"+ EXECUTION_END = "execution_end"+# Model / tool boundaries (legacy-compatible)PRE_MODEL_CALL = "pre_model_call"POST_MODEL_CALL = "post_model_call"diff --git a/lib/crewai/tests/hooks/test_interception_conformance.py b/lib/crewai/tests/hooks/test_interception_conformance.pynew file mode 100644index 000000000..9c2965bd2--- /dev/null+++ b/lib/crewai/tests/hooks/test_interception_conformance.py@@ -0,0 +1,88 @@+"""Conformance suite for the framework-native interception points.++For each wired point this suite asserts the shared contract: the probe hook+sees a well-shaped payload, an in-place/returned modification is honored, and a+:class:`HookAborted` interrupts the step.+"""++from __future__ import annotations++from crewai.flow.flow import Flow, listen, start+from crewai.hooks.dispatch import (+ HookAborted,+ InterceptionPoint,+ clear_all,+ on,+)+import pytest++[email protected](autouse=True)+def clear_dispatch_registry():+ clear_all()+ yield+ clear_all()+++class _SimpleFlow(Flow):+ @start()+ def begin(self):+ return "begin"++ @listen(begin)+ def finish(self, _):+ return "flow-result"+++class TestFlowExecutionBoundaries:+ """execution_start / input / output / execution_end on a flow."""++ def test_all_boundary_points_fire_once(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)++ _SimpleFlow().kickoff(inputs={"seed": 1})++ assert fired == [+ "execution_start",+ "input",+ "output",+ "execution_end",+ ]++ def test_output_modification_is_honored(self):+ @on(InterceptionPoint.OUTPUT)+ def rewrite(ctx):+ return "intercepted"++ result = _SimpleFlow().kickoff()+ assert result == "intercepted"++ def test_input_payload_carries_inputs(self):+ seen: dict = {}++ @on(InterceptionPoint.INPUT)+ def capture(ctx):+ seen.update(ctx.payload or {})++ _SimpleFlow().kickoff(inputs={"seed": 42})+ assert seen == {"seed": 42}++ def test_abort_at_execution_start_interrupts(self):+ @on(InterceptionPoint.EXECUTION_START)+ def block(ctx):+ raise HookAborted(reason="not allowed", source="policy")++ with pytest.raises(HookAborted) as exc:+ _SimpleFlow().kickoff()+ assert exc.value.reason == "not allowed"