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.

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.py
index 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 FlowTrackable
from crewai.knowledge.knowledge import Knowledge, _resolve_knowledge_sources
from 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.py
new file mode 100644
index 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.py
index 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 integration
llm: LLM model string for outcome collapsing
requested_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 = None
requested_at: datetime = field(default_factory=datetime.now)
+ execution_uuid: str | None = None
@staticmethod
def _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__.py
index 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=llm
if 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, self
diff --git a/lib/crewai/tests/test_execution_uuid.py b/lib/crewai/tests/test_execution_uuid.py
new file mode 100644
index 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