feat: add crew context tracking for LLM guardrail events (#3111)

Add crew context tracking using OpenTelemetry baggage for thread-safe propagation. Context is set during kickoff and cleaned up in finally block. Added thread safety tests with mocked agent execution.

src/crewai/crew.py

@@ -18,6 +18,11 @@ from typing import (
     cast,
 )
 
+from opentelemetry import baggage
+from opentelemetry.context import attach, detach
+
+from crewai.utilities.crew.models import CrewContext
+
 from pydantic import (
     UUID4,
     BaseModel,
@@ -616,6 +621,11 @@ class Crew(FlowTrackable, BaseModel):
         self,
         inputs: Optional[Dict[str, Any]] = None,
     ) -> CrewOutput:
+        ctx = baggage.set_baggage(
+            "crew_context", CrewContext(id=str(self.id), key=self.key)
+        )
+        token = attach(ctx)
+
         try:
             for before_callback in self.before_kickoff_callbacks:
                 if inputs is None:
@@ -676,6 +686,8 @@ class Crew(FlowTrackable, BaseModel):
                 CrewKickoffFailedEvent(error=str(e), crew_name=self.name or "crew"),
             )
             raise
+        finally:
+            detach(token)
 
     def kickoff_for_each(self, inputs: List[Dict[str, Any]]) -> List[CrewOutput]:
         """Executes the Crew's workflow for each input in the list and aggregates results."""

src/crewai/utilities/crew/__init__.py

@@ -0,0 +1 @@
+"""Crew-specific utilities."""

src/crewai/utilities/crew/crew_context.py

@@ -0,0 +1,16 @@
+"""Context management utilities for tracking crew and task execution context using OpenTelemetry baggage."""
+
+from typing import Optional
+
+from opentelemetry import baggage
+
+from crewai.utilities.crew.models import CrewContext
+
+
+def get_crew_context() -> Optional[CrewContext]:
+    """Get the current crew context from OpenTelemetry baggage.
+
+    Returns:
+        CrewContext instance containing crew context information, or None if no context is set
+    """
+    return baggage.get_baggage("crew_context")

src/crewai/utilities/crew/models.py

@@ -0,0 +1,16 @@
+"""Models for crew-related data structures."""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class CrewContext(BaseModel):
+    """Model representing crew context information."""
+
+    id: Optional[str] = Field(
+        default=None, description="Unique identifier for the crew"
+    )
+    key: Optional[str] = Field(
+        default=None, description="Optional crew key/name for identification"
+    )

src/crewai/utilities/events/llm_guardrail_events.py

@@ -1,3 +1,4 @@
+from inspect import getsource
 from typing import Any, Callable, Optional, Union
 
 from crewai.utilities.events.base_events import BaseEvent
@@ -16,23 +17,26 @@ class LLMGuardrailStartedEvent(BaseEvent):
     retry_count: int
 
     def __init__(self, **data):
-        from inspect import getsource
-
         from crewai.tasks.llm_guardrail import LLMGuardrail
         from crewai.tasks.hallucination_guardrail import HallucinationGuardrail
 
         super().__init__(**data)
 
-        if isinstance(self.guardrail, LLMGuardrail) or isinstance(
-            self.guardrail, HallucinationGuardrail
-        ):
+        if isinstance(self.guardrail, (LLMGuardrail, HallucinationGuardrail)):
             self.guardrail = self.guardrail.description.strip()
         elif isinstance(self.guardrail, Callable):
             self.guardrail = getsource(self.guardrail).strip()
 
 
 class LLMGuardrailCompletedEvent(BaseEvent):
-    """Event emitted when a guardrail task completes"""
+    """Event emitted when a guardrail task completes
+
+    Attributes:
+        success: Whether the guardrail validation passed
+        result: The validation result
+        error: Error message if validation failed
+        retry_count: The number of times the guardrail has been retried
+    """
 
     type: str = "llm_guardrail_completed"
     success: bool