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: emit LLMGuardrailCompletedEvent when a guardrail raises (#8403)

Wilson_Jiang90192810cf93
diff --git a/lib/crewai/src/crewai/utilities/guardrail.py b/lib/crewai/src/crewai/utilities/guardrail.py
index 8454ffd92..e0dfa8659 100644
--- a/lib/crewai/src/crewai/utilities/guardrail.py
+++ b/lib/crewai/src/crewai/utilities/guardrail.py
@@ -188,6 +188,24 @@ def process_guardrail(
),
)
raise
+ except Exception as e:
+ # an exception ends the validation too; without a terminal event the
+ # "evaluate guardrail" span survives until the end-of-execution sweep
+ # closes it as orphaned, and the trace loses the real error
+ crewai_event_bus.emit(
+ event_source,
+ LLMGuardrailCompletedEvent(
+ success=False,
+ result=None,
+ error=f"{type(e).__name__}: {e}",
+ retry_count=retry_count,
+ guardrail_type=started_event.guardrail_type,
+ guardrail_name=started_event.guardrail_name,
+ from_agent=from_agent,
+ from_task=from_task,
+ ),
+ )
+ raise
guardrail_result = GuardrailResult.from_tuple(result)
diff --git a/lib/crewai/tests/test_guardrail_events_on_exception.py b/lib/crewai/tests/test_guardrail_events_on_exception.py
new file mode 100644
index 000000000..026c615bc
--- /dev/null
+++ b/lib/crewai/tests/test_guardrail_events_on_exception.py
@@ -0,0 +1,76 @@
+"""A guardrail that raises owes its started event a terminal one.
+
+``process_guardrail`` emits ``LLMGuardrailStartedEvent`` before calling the
+guardrail and ``LLMGuardrailCompletedEvent`` after it returns. A deny
+(``HookAborted``) already gets its terminal event; an ordinary exception did
+not, so the tracing listener's "evaluate guardrail" span stayed open until the
+end-of-execution sweep closed it as "orphaned", losing the real error from the
+trace. The caller sees the exception either way — only the event pairing
+differs.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from crewai.events.event_bus import crewai_event_bus
+from crewai.events.types.llm_guardrail_events import (
+ LLMGuardrailCompletedEvent,
+ LLMGuardrailStartedEvent,
+)
+from crewai.tasks.task_output import TaskOutput
+from crewai.utilities.guardrail import process_guardrail
+
+from tests.utils import wait_for_event_handlers
+
+
+def test_a_raising_guardrail_still_reports_the_validation_it_started():
+ task_output = TaskOutput(
+ description="Say hi", raw="hi", agent="Doer", expected_output="A greeting."
+ )
+
+ def raising_guardrail(_output: Any) -> tuple[bool, str]:
+ raise ValueError("guardrail exploded")
+
+ started: list[LLMGuardrailStartedEvent] = []
+ completed: list[LLMGuardrailCompletedEvent] = []
+
+ with crewai_event_bus.scoped_handlers():
+
+ @crewai_event_bus.on(LLMGuardrailStartedEvent)
+ def _on_started(_source: Any, event: LLMGuardrailStartedEvent) -> None:
+ started.append(event)
+
+ @crewai_event_bus.on(LLMGuardrailCompletedEvent)
+ def _on_completed(_source: Any, event: LLMGuardrailCompletedEvent) -> None:
+ completed.append(event)
+
+ with pytest.raises(ValueError, match="guardrail exploded"):
+ process_guardrail(
+ output=task_output, guardrail=raising_guardrail, retry_count=0
+ )
+
+ wait_for_event_handlers()
+
+ assert len(started) == 1
+ assert len(completed) == 1
+ assert completed[0].success is False
+ assert "guardrail exploded" in (completed[0].error or "")
+
+
+def test_a_raising_guardrail_keeps_the_exception_for_the_caller():
+ task_output = TaskOutput(
+ description="Say hi", raw="hi", agent="Doer", expected_output="A greeting."
+ )
+
+ def raising_guardrail(_output: Any) -> tuple[bool, str]:
+ raise RuntimeError("context lost")
+
+ with crewai_event_bus.scoped_handlers():
+ with pytest.raises(RuntimeError, match="context lost"):
+ process_guardrail(
+ output=task_output, guardrail=raising_guardrail, retry_count=1
+ )
+ wait_for_event_handlers()