Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat(execution): introduce execution context management with UUID sup… (#6988)
Lorenze Jay1818792fb1d3
diff --git a/lib/crewai/src/crewai/crew.py b/lib/crewai/src/crewai/crew.pyindex 5b7908cff..d3c54f513 100644--- a/lib/crewai/src/crewai/crew.py+++ b/lib/crewai/src/crewai/crew.py@@ -92,6 +92,10 @@ from crewai.events.types.crew_events import (CrewTrainFailedEvent,CrewTrainStartedEvent,)+from crewai.execution import (+ begin_execution,+ end_execution,+)from crewai.flow.flow_trackable import FlowTrackablefrom crewai.knowledge.knowledge import Knowledge, _resolve_knowledge_sourcesfrom crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSource@@ -1038,6 +1042,8 @@ class Crew(FlowTrackable, BaseModel):)token = attach(baggage_ctx)+ execution_token = begin_execution()+runtime_scope = crewai_event_bus._enter_runtime_scope()try:inputs = prepare_kickoff(self, inputs, input_files)@@ -1076,6 +1082,7 @@ class Crew(FlowTrackable, BaseModel):self._drain_memory_writes()clear_files(self.id)detach(token)+ end_execution(execution_token)crewai_event_bus._exit_runtime_scope(runtime_scope)def _post_kickoff(self, result: CrewOutput) -> CrewOutput:@@ -1252,6 +1259,8 @@ class Crew(FlowTrackable, BaseModel):)token = attach(baggage_ctx)+ execution_token = begin_execution()+runtime_scope = crewai_event_bus._enter_runtime_scope()try:inputs = prepare_kickoff(self, inputs, input_files)@@ -1290,6 +1299,7 @@ class Crew(FlowTrackable, BaseModel):self._drain_memory_writes()clear_files(self.id)detach(token)+ end_execution(execution_token)crewai_event_bus._exit_runtime_scope(runtime_scope)async def akickoff_for_each(diff --git a/lib/crewai/src/crewai/execution.py b/lib/crewai/src/crewai/execution.pynew file mode 100644index 000000000..25a3a3443--- /dev/null+++ b/lib/crewai/src/crewai/execution.py@@ -0,0 +1,70 @@+"""Per-run execution identity for OSS traces.++Wharf keys spans by ``crewai.execution_uuid``. Enterprise stamps that from the+Celery ``kickoff_id`` inside ``telemetry_session``. Standalone OSS has no such+session, so crew/flow ``kickoff`` creates a uuid for the **outermost** run and+nested kickoffs (crew-in-flow, AgentExecutor, child flows) inherit it via+contextvars on the execution thread.++Minting lives on the kickoff call path (not the event bus): bus handlers run+on worker threads and cannot publish contextvars back to the user thread.++Enterprise (or any host) can call :func:`set_execution_uuid` before kickoff;+:func:`begin_execution` will not overwrite it.+"""++from __future__ import annotations++import contextvars+from uuid import uuid4+++_current_execution_uuid: contextvars.ContextVar[str | None] = contextvars.ContextVar(+ "crewai_execution_uuid", default=None+)+++def get_execution_uuid() -> str | None:+ """Return the active execution uuid, if any."""+ return _current_execution_uuid.get()+++def set_execution_uuid(execution_uuid: str) -> contextvars.Token[str | None]:+ """Bind an execution uuid for the current context.++ Use this from enterprise / hosts that already own the run id (e.g. Celery+ ``kickoff_id``). Overwrites any previously bound value.+ """+ if not execution_uuid:+ raise ValueError("execution_uuid must be a non-empty string")+ return _current_execution_uuid.set(execution_uuid)+++def clear_execution_uuid(token: contextvars.Token[str | None]) -> None:+ """Restore the execution uuid that was active before ``token`` was issued.++ ``token`` is required so this cannot wipe an outer kickoff's uuid.+ """+ _current_execution_uuid.reset(token)+++def begin_execution(+ execution_uuid: str | None = None,+) -> contextvars.Token[str | None] | None:+ """Start an execution context unless one is already active.++ The outermost crew or flow receives a new uuid by default. Nested+ executions inherit the active value and return no reset token.+ """+ if _current_execution_uuid.get() is not None:+ return None+ return set_execution_uuid(execution_uuid or str(uuid4()))+++def end_execution(token: contextvars.Token[str | None] | None) -> None:+ """End an execution context owned by the current kickoff.++ Nested kickoffs pass ``None`` and leave the outer uuid in place.+ """+ if token is not None:+ clear_execution_uuid(token)diff --git a/lib/crewai/src/crewai/flow/async_feedback/types.py b/lib/crewai/src/crewai/flow/async_feedback/types.pyindex d8c834fb1..e9b5ec92f 100644--- a/lib/crewai/src/crewai/flow/async_feedback/types.py+++ b/lib/crewai/src/crewai/flow/async_feedback/types.py@@ -37,6 +37,10 @@ class PendingFeedbackContext:metadata: Optional metadata for external system integrationllm: LLM model string for outcome collapsingrequested_at: When the feedback was requested+ execution_uuid: Outermost kickoff uuid to restore on resume so traces+ stay on the same run after HITL pause. ``None`` only for pending+ rows persisted before this field existed; resume then creates a+ new uuid. New pauses always store a value.Example:```python@@ -62,6 +66,7 @@ class PendingFeedbackContext:metadata: dict[str, Any] = field(default_factory=dict)llm: dict[str, Any] | str | None = Nonerequested_at: datetime = field(default_factory=datetime.now)+ execution_uuid: str | None = None@staticmethoddef _make_json_safe(value: Any) -> Any:@@ -106,6 +111,7 @@ class PendingFeedbackContext:"metadata": self._make_json_safe(self.metadata),"llm": self.llm,"requested_at": self.requested_at.isoformat(),+ "execution_uuid": self.execution_uuid,}@classmethod@@ -135,6 +141,7 @@ class PendingFeedbackContext:metadata=data.get("metadata", {}),llm=data.get("llm"),requested_at=requested_at,+ execution_uuid=data.get("execution_uuid"),)diff --git a/lib/crewai/src/crewai/flow/runtime/__init__.py b/lib/crewai/src/crewai/flow/runtime/__init__.pyindex 875db3800..8e5580280 100644--- a/lib/crewai/src/crewai/flow/runtime/__init__.py+++ b/lib/crewai/src/crewai/flow/runtime/__init__.py@@ -78,6 +78,11 @@ from crewai.events.types.flow_events import (MethodExecutionStartedEvent,)from crewai.events.types.llm_events import LLMCallCompletedEvent+from crewai.execution import (+ begin_execution,+ end_execution,+ get_execution_uuid,+)from crewai.flow.async_feedback.types import (HumanFeedbackPending,HumanFeedbackProvider,@@ -1342,6 +1347,8 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):"No pending feedback context. Use from_pending() to restore a paused flow.")+ execution_token = begin_execution(self._pending_feedback_context.execution_uuid)+# Force `current_flow_id` to this flow's match id for the# duration of the resume so the usage listener's filter passes# even when resume runs under another flow's active context.@@ -1368,6 +1375,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):self._detach_usage_aggregation_listener()if flow_id_token is not None:current_flow_id.reset(flow_id_token)+ end_execution(execution_token)async def _resume_async_body(self, feedback: str = "", hook_state: dict[str, bool] | None = None@@ -2131,6 +2139,8 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):if current_flow_request_id.get() is None:request_id_token = current_flow_request_id.set(self.flow_id)+ execution_token = begin_execution()+runtime_scope = crewai_event_bus._enter_runtime_scope()# Reentrant kickoffs on the same Flow share the outer call's@@ -2486,6 +2496,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):current_flow_id.reset(flow_id_token)if flow_inputs_token is not None:detach(flow_inputs_token)+ end_execution(execution_token)detach(flow_token)crewai_event_bus._exit_runtime_scope(runtime_scope)@@ -3532,6 +3543,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):llm=llmif llm is None or isinstance(llm, (str, dict))else _serialize_llm_for_context(llm),+ execution_uuid=get_execution_uuid(),)feedback_value = await asyncio.to_thread(provider.request_feedback, context, selfdiff --git a/lib/crewai/tests/test_execution_uuid.py b/lib/crewai/tests/test_execution_uuid.pynew file mode 100644index 000000000..7fdc6cb45--- /dev/null+++ b/lib/crewai/tests/test_execution_uuid.py@@ -0,0 +1,238 @@+"""Tests for OSS execution uuid creation and nesting inheritance."""++from __future__ import annotations++import pytest++from crewai.execution import (+ _current_execution_uuid,+ begin_execution,+ clear_execution_uuid,+ end_execution,+ get_execution_uuid,+ set_execution_uuid,+)++[email protected](autouse=True)+def _isolate_execution_uuid() -> None:+ token = _current_execution_uuid.set(None)+ yield+ _current_execution_uuid.reset(token)+++def test_begin_creates_when_empty() -> None:+ assert get_execution_uuid() is None+ first_token = begin_execution()+ first = get_execution_uuid()+ second_token = begin_execution()+ assert first+ assert get_execution_uuid() == first+ assert second_token is None+ end_execution(second_token)+ end_execution(first_token)+++def test_begin_does_not_overwrite_existing() -> None:+ token = set_execution_uuid("enterprise-kickoff-id")+ try:+ assert begin_execution("should-not-win") is None+ assert get_execution_uuid() == "enterprise-kickoff-id"+ finally:+ clear_execution_uuid(token)+++def test_set_rejects_empty() -> None:+ with pytest.raises(ValueError, match="non-empty"):+ set_execution_uuid("")+++def test_nested_execution_inherits_and_only_owner_clears() -> None:+ parent_token = begin_execution()+ parent_id = get_execution_uuid()+ child_token = begin_execution()++ assert parent_id+ assert child_token is None+ assert get_execution_uuid() == parent_id++ end_execution(child_token)+ assert get_execution_uuid() == parent_id++ end_execution(parent_token)+ assert get_execution_uuid() is None+++def test_two_sequential_outer_runs_get_distinct_uuids() -> None:+ first_token = begin_execution()+ first_id = get_execution_uuid()+ end_execution(first_token)+ second_token = begin_execution()+ second_id = get_execution_uuid()+ end_execution(second_token)++ assert first_id != second_id+++def test_flow_kickoff_creates_and_clears_execution_uuid() -> None:+ from crewai.flow.flow import Flow, start++ seen: dict[str, str | None] = {}++ class ProbeFlow(Flow):+ @start()+ def begin(self) -> str:+ seen["during"] = get_execution_uuid()+ return "ok"++ flow = ProbeFlow()+ assert get_execution_uuid() is None+ flow.kickoff()+ assert seen["during"]+ assert get_execution_uuid() is None+++def test_flow_kickoff_inherits_enterprise_execution_uuid() -> None:+ from crewai.flow.flow import Flow, start++ seen: dict[str, str | None] = {}++ class ProbeFlow(Flow):+ @start()+ def begin(self) -> str:+ seen["during"] = get_execution_uuid()+ return "ok"++ token = set_execution_uuid("celery-kickoff-id")+ try:+ ProbeFlow().kickoff()+ assert seen["during"] == "celery-kickoff-id"+ # Owner was enterprise set(), not the flow — still set here.+ assert get_execution_uuid() == "celery-kickoff-id"+ finally:+ clear_execution_uuid(token)++ assert get_execution_uuid() is None+++async def test_crew_akickoff_creates_and_clears_execution_uuid() -> None:+ from unittest.mock import patch++ from crewai import Agent, Crew, Task+ from crewai.tasks.task_output import TaskOutput++ seen: dict[str, str | None] = {}+ agent = Agent(role="r", goal="g", backstory="b", llm="gpt-4o-mini")+ task = Task(description="d", expected_output="o", agent=agent)+ crew = Crew(agents=[agent], tasks=[task])++ async def capture(*_args: object, **_kwargs: object) -> TaskOutput:+ seen["during"] = get_execution_uuid()+ return TaskOutput(description="d", raw="ok", agent="r")++ with patch("crewai.task.Task.aexecute_sync", side_effect=capture):+ assert get_execution_uuid() is None+ await crew.akickoff()++ assert seen["during"]+ assert get_execution_uuid() is None+++async def test_crew_akickoff_inherits_enterprise_execution_uuid() -> None:+ from unittest.mock import patch++ from crewai import Agent, Crew, Task+ from crewai.tasks.task_output import TaskOutput++ seen: dict[str, str | None] = {}+ agent = Agent(role="r", goal="g", backstory="b", llm="gpt-4o-mini")+ task = Task(description="d", expected_output="o", agent=agent)+ crew = Crew(agents=[agent], tasks=[task])++ async def capture(*_args: object, **_kwargs: object) -> TaskOutput:+ seen["during"] = get_execution_uuid()+ return TaskOutput(description="d", raw="ok", agent="r")++ token = set_execution_uuid("celery-kickoff-id")+ try:+ with patch("crewai.task.Task.aexecute_sync", side_effect=capture):+ await crew.akickoff()+ assert seen["during"] == "celery-kickoff-id"+ assert get_execution_uuid() == "celery-kickoff-id"+ finally:+ clear_execution_uuid(token)++ assert get_execution_uuid() is None+++def test_flow_pause_persists_execution_uuid_and_resume_restores_it() -> None:+ import os+ import tempfile++ from crewai.flow import Flow, human_feedback, listen, start+ from crewai.flow.async_feedback.types import (+ HumanFeedbackPending,+ PendingFeedbackContext,+ )+ from crewai.flow.persistence import SQLiteFlowPersistence++ seen: dict[str, str | None] = {}++ class PausingProvider:+ def request_feedback(+ self, context: PendingFeedbackContext, flow: Flow+ ) -> str:+ raise HumanFeedbackPending(context=context)++ class ReviewFlow(Flow):+ @start()+ @human_feedback(message="Review:", provider=PausingProvider())+ def generate(self) -> str:+ seen["during_kickoff"] = get_execution_uuid()+ return "draft"++ @listen(generate)+ def process(self, result: object) -> str:+ seen["during_resume"] = get_execution_uuid()+ return "done"++ with tempfile.TemporaryDirectory() as tmpdir:+ persistence = SQLiteFlowPersistence(os.path.join(tmpdir, "test.db"))+ pending = ReviewFlow(persistence=persistence).kickoff()+ assert isinstance(pending, HumanFeedbackPending)+ paused_id = seen["during_kickoff"]+ assert paused_id+ assert pending.context.execution_uuid == paused_id+ assert get_execution_uuid() is None++ ReviewFlow.from_pending(pending.context.flow_id, persistence).resume("ok")+ assert seen["during_resume"] == paused_id+ assert get_execution_uuid() is None+++def test_pending_feedback_context_roundtrips_execution_uuid() -> None:+ from crewai.flow.async_feedback.types import PendingFeedbackContext++ original = PendingFeedbackContext(+ flow_id="flow-1",+ flow_class="test.Flow",+ method_name="review",+ method_output="draft",+ message="Review:",+ execution_uuid="kickoff-uuid",+ )+ restored = PendingFeedbackContext.from_dict(original.to_dict())+ assert restored.execution_uuid == "kickoff-uuid"++ legacy = PendingFeedbackContext.from_dict(+ {+ "flow_id": "flow-1",+ "flow_class": "test.Flow",+ "method_name": "review",+ "method_output": "draft",+ "message": "Review:",+ }+ )+ assert legacy.execution_uuid is None