🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
feat(workforce): add stream chunk events to workforce callback system (#4041)
Lei Zhangb284ffd04195
diff --git a/camel/societies/workforce/events.py b/camel/societies/workforce/events.pyindex f2e264d75..4f31acf58 100644--- a/camel/societies/workforce/events.py+++ b/camel/societies/workforce/events.py@@ -23,6 +23,7 @@ class WorkforceEventBase(BaseModel):model_config = ConfigDict(frozen=True, extra='forbid')event_type: Literal["log",+ "stream_chunk","task_decomposed","task_created","task_assigned",@@ -60,6 +61,14 @@ class LogEvent(WorkforceEventBase):) = None+class StreamChunkEvent(WorkforceEventBase):+ event_type: Literal["stream_chunk"] = "stream_chunk"+ text: str+ stream_accumulate_mode: str = "accumulate"+ task_id: Optional[str] = None+ worker_id: Optional[str] = None++class WorkerCreatedEvent(WorkforceEventBase):event_type: Literal["worker_created"] = "worker_created"worker_id: str@@ -144,6 +153,7 @@ class QueueStatusEvent(WorkforceEventBase):WorkforceEvent = Union[LogEvent,+ StreamChunkEvent,TaskDecomposedEvent,TaskCreatedEvent,TaskAssignedEvent,diff --git a/camel/societies/workforce/workforce.py b/camel/societies/workforce/workforce.pyindex bea689dcc..e1fff726c 100644--- a/camel/societies/workforce/workforce.py+++ b/camel/societies/workforce/workforce.py@@ -102,6 +102,7 @@ from camel.utils import (from .events import (AllTasksCompletedEvent,LogEvent,+ StreamChunkEvent,TaskAssignedEvent,TaskCompletedEvent,TaskCreatedEvent,@@ -627,38 +628,34 @@ class Workforce(BaseNode):async def _on_worker_stream_chunk(self, chunk: "ChatAgentResponse", worker_id: str, task_id: str) -> None:- r"""Normalize worker stream chunks and dispatch to user callback."""- if self._user_stream_callback is None:- return-- if chunk.msg is None or chunk.msg.content is None:- return-- mode = "accumulate"- if chunk.info:- mode = chunk.info.get("stream_accumulate_mode", mode)- if "mode" in chunk.info:- mode = chunk.info["mode"]-- content = chunk.msg.content- key = (worker_id, task_id)+ r"""Normalize worker stream chunks, emit a `StreamChunkEvent`,+ and dispatch to the user callback."""+ stream_id = f"{worker_id}:{task_id}"+ stream_payload = self._extract_stream_chunk(+ chunk,+ stream_id=stream_id,+ )- if mode == "accumulate":- previous = self._stream_progress.get(key, "")- if content.startswith(previous):- text = content[len(previous) :]- else:- text = content- self._stream_progress[key] = content- else:- text = content+ try:+ if stream_payload is None:+ return- if not text:- return+ text, stream_accumulate_mode = stream_payload+ self._emit_stream_chunk_event(+ text=text,+ stream_accumulate_mode=stream_accumulate_mode,+ task_id=task_id,+ worker_id=worker_id,+ )- maybe = self._user_stream_callback(worker_id, task_id, text, mode)- if asyncio.iscoroutine(maybe):- await maybe+ if self._user_stream_callback is not None:+ maybe = self._user_stream_callback(+ worker_id, task_id, text, stream_accumulate_mode+ )+ if asyncio.iscoroutine(maybe):+ await maybe+ finally:+ self._clear_stream_progress_if_final(chunk, stream_id)def _notify_worker_created(self,@@ -1270,23 +1267,97 @@ class Workforce(BaseNode):return shared_memory- def _on_stream_callback(self, chunk: ChatAgentResponse) -> None:- # TODO (transitional): This is a local, best-effort stream speed- # logger used only until streaming telemetry is moved into- # WorkforceCallback. In a follow-up PR, replace this direct logging- # with callback-driven events/metrics and remove this helper path.- now = time.monotonic()- if not hasattr(self, "_stream_start_ts"):- self._stream_start_ts = now- self._stream_chars = 0- content = chunk.msg.content or ""- self._stream_chars += len(content)- elapsed = now - self._stream_start_ts- if elapsed > 0:- speed = self._stream_chars / elapsed # chars per second- logger.info(- f"Stream Speed: {speed:.1f} chars/s (elapsed {elapsed:.2f}s)"+ def _extract_stream_chunk(+ self,+ chunk: ChatAgentResponse,+ *,+ stream_id: str,+ ) -> Optional[Tuple[str, str]]:+ r"""Extract normalized text and mode from a stream chunk."""+ if chunk.msg is None or chunk.msg.content is None:+ return None++ stream_accumulate_mode: str = "accumulate"+ if chunk.info:+ # `mode` is a legacy/custom chunk fallback; current producers use+ # `stream_accumulate_mode`.+ raw_stream_accumulate_mode = chunk.info.get(+ "stream_accumulate_mode",+ chunk.info.get("mode", stream_accumulate_mode),+ )+ if raw_stream_accumulate_mode in ("delta", "accumulate"):+ stream_accumulate_mode = raw_stream_accumulate_mode++ content = chunk.msg.content+ progress_key = ("stream", stream_id)++ if stream_accumulate_mode == "accumulate":+ previous = self._stream_progress.get(progress_key, "")+ if content.startswith(previous):+ text = content[len(previous) :]+ else:+ text = content+ self._stream_progress[progress_key] = content+ else:+ text = content++ if not text:+ return None++ return text, stream_accumulate_mode++ def _emit_stream_chunk_event(+ self,+ *,+ text: str,+ stream_accumulate_mode: str,+ task_id: Optional[str] = None,+ worker_id: Optional[str] = None,+ metadata: Optional[Dict[str, Any]] = None,+ ) -> None:+ r"""Emit a stream chunk event to all registered callbacks."""+ event = StreamChunkEvent(+ text=text,+ stream_accumulate_mode=stream_accumulate_mode,+ task_id=task_id,+ worker_id=worker_id,+ metadata=metadata,+ )+ for cb in self._callbacks:+ cb.log_stream_chunk(event)++ def _clear_stream_progress_if_final(+ self,+ chunk: ChatAgentResponse,+ stream_id: str,+ ) -> None:+ r"""Clear accumulated stream progress when a stream is complete."""+ chunk_info = getattr(chunk, "info", None)+ if getattr(chunk, "terminated", False) or (+ isinstance(chunk_info, dict) and chunk_info.get("partial") is False+ ):+ self._stream_progress.pop(("stream", stream_id), None)++ def _on_stream_callback(+ self,+ chunk: ChatAgentResponse,+ ) -> None:+ stream_id = "internal"+ stream_payload = self._extract_stream_chunk(+ chunk,+ stream_id=stream_id,+ )+ try:+ if stream_payload is None:+ return++ text, stream_accumulate_mode = stream_payload+ self._emit_stream_chunk_event(+ text=text,+ stream_accumulate_mode=stream_accumulate_mode,)+ finally:+ self._clear_stream_progress_if_final(chunk, stream_id)def _share_memory_with_agents(self, shared_memory: Dict[str, List]@@ -1467,7 +1538,11 @@ class Workforce(BaseNode):del self._assignees[task_id]# Clean streaming progress for completed/failed task chunks.- stale_keys = [k for k in self._stream_progress if k[1] == task_id]+ stale_keys = [+ key+ for key in self._stream_progress+ if key[1] == task_id or key[1].endswith(f":{task_id}")+ ]for key in stale_keys:del self._stream_progress[key]diff --git a/camel/societies/workforce/workforce_callback.py b/camel/societies/workforce/workforce_callback.pyindex 42c7bab93..132a1971f 100644--- a/camel/societies/workforce/workforce_callback.py+++ b/camel/societies/workforce/workforce_callback.py@@ -21,6 +21,7 @@ from colorama import Forefrom .events import (AllTasksCompletedEvent,LogEvent,+ StreamChunkEvent,TaskAssignedEvent,TaskCompletedEvent,TaskCreatedEvent,@@ -64,6 +65,13 @@ class WorkforceCallback(ABC):) -> None:pass+ @abstractmethod+ def log_stream_chunk(+ self,+ event: StreamChunkEvent,+ ) -> None:+ pass+@abstractmethoddef log_task_created(self,diff --git a/camel/societies/workforce/workforce_logger.py b/camel/societies/workforce/workforce_logger.pyindex bd6639629..e5f818cfb 100644--- a/camel/societies/workforce/workforce_logger.py+++ b/camel/societies/workforce/workforce_logger.py@@ -20,6 +20,7 @@ from camel.societies.workforce.events import (AllTasksCompletedEvent,LogEvent,QueueStatusEvent,+ StreamChunkEvent,TaskAssignedEvent,TaskCompletedEvent,TaskCreatedEvent,@@ -40,13 +41,31 @@ logger = get_logger(__name__)class WorkforceLogger(WorkforceCallback, WorkforceMetrics):r"""Logs events and metrics for a Workforce instance."""- def __init__(self, workforce_id: str):+ def __init__(+ self,+ workforce_id: str,+ *,+ log_stream_chunks: bool = False,+ stream_chunk_text_limit: Optional[int] = 1000,+ ):"""Initializes the WorkforceLogger.Args:workforce_id (str): The unique identifier for the workforce.+ log_stream_chunks (bool): Whether to persist streaming chunk+ events. Disabled by default to avoid unbounded in-memory logs+ for high-volume streams.+ stream_chunk_text_limit (Optional[int]): Maximum number of+ characters to store for each stream chunk when+ `log_stream_chunks` is enabled. Set to `None` to store full+ chunk text."""+ if stream_chunk_text_limit is not None and stream_chunk_text_limit < 0:+ raise ValueError("stream_chunk_text_limit must be non-negative")+self.workforce_id: str = workforce_id+ self.log_stream_chunks: bool = log_stream_chunks+ self.stream_chunk_text_limit: Optional[int] = stream_chunk_text_limitself.log_entries: List[Dict[str, Any]] = []self._task_hierarchy: Dict[str, Dict[str, Any]] = {}self._worker_information: Dict[str, Dict[str, Any]] = {}@@ -57,6 +76,32 @@ class WorkforceLogger(WorkforceCallback, WorkforceMetrics):colored_message = self._get_color_message(event)print(colored_message)+ def log_stream_chunk(self, event: StreamChunkEvent) -> None:+ r"""Logs streaming chunk events."""+ if not self.log_stream_chunks:+ return++ text = event.text+ text_length = len(text)+ text_truncated = False+ if (+ self.stream_chunk_text_limit is not None+ and text_length > self.stream_chunk_text_limit+ ):+ text = text[: self.stream_chunk_text_limit]+ text_truncated = True++ self._log_event(+ event_type=event.event_type,+ text=text,+ text_length=text_length,+ text_truncated=text_truncated,+ stream_accumulate_mode=event.stream_accumulate_mode,+ task_id=event.task_id,+ worker_id=event.worker_id,+ metadata=event.metadata or {},+ )+def _log_event(self, event_type: str, **kwargs: Any) -> None:r"""Internal method to create and store a log entry.diff --git a/examples/workforce/workforce_callbacks_example.py b/examples/workforce/workforce_callbacks_example.pyindex 031b168f9..eb96ad691 100644--- a/examples/workforce/workforce_callbacks_example.py+++ b/examples/workforce/workforce_callbacks_example.py@@ -21,6 +21,7 @@ Includes:"""import json+import timefrom camel.agents import ChatAgentfrom camel.configs import ChatGPTConfig@@ -31,6 +32,7 @@ from camel.societies.workforce import FailureHandlingConfigfrom camel.societies.workforce.events import (AllTasksCompletedEvent,LogEvent,+ StreamChunkEvent,TaskAssignedEvent,TaskCompletedEvent,TaskCreatedEvent,@@ -81,6 +83,7 @@ class PrintCallback(WorkforceCallback):def __init__(self, stream_buffers: dict[tuple[str, str], list[str]]):self._stream_buffers = stream_buffers+ self._stream_stats: dict[tuple[str, str], tuple[float, int, int]] = {}def log_message(self, event: LogEvent) -> None:print(@@ -88,6 +91,32 @@ class PrintCallback(WorkforceCallback):f"color={event.color}")+ def log_stream_chunk(self, event: StreamChunkEvent) -> None:+ if not event.worker_id or not event.task_id:+ return++ key = (event.worker_id, event.task_id)+ self._stream_buffers.setdefault(key, []).append(event.text)++ now = time.monotonic()+ last_ts, window_chars, total_chars = self._stream_stats.get(+ key, (now, 0, 0)+ )+ chunk_chars = len(event.text)+ window_chars += chunk_chars+ total_chars += chunk_chars+ elapsed = now - last_ts++ if elapsed >= 1.0:+ chars_per_second = window_chars / elapsed+ print(+ f"[StreamProgress][{key[0]}][{key[1]}] "+ f"{chars_per_second:.1f} chars/s, total={total_chars}"+ )+ self._stream_stats[key] = (now, 0, total_chars)+ else:+ self._stream_stats[key] = (last_ts, window_chars, total_chars)+def log_task_created(self, event: TaskCreatedEvent) -> None:print(f"[PrintCallback] task_created: id={event.task_id}, "@@ -125,6 +154,7 @@ class PrintCallback(WorkforceCallback):)key = (event.worker_id, event.task_id)chunks = self._stream_buffers.pop(key, [])+ self._stream_stats.pop(key, None)if chunks:merged_text = "".join(chunks).strip()if merged_text:@@ -137,6 +167,10 @@ class PrintCallback(WorkforceCallback):f"[PrintCallback] task_failed: task={event.task_id}, "f"err={event.error_message}")+ if event.worker_id:+ key = (event.worker_id, event.task_id)+ self._stream_buffers.pop(key, None)+ self._stream_stats.pop(key, None)def log_worker_created(self, event: WorkerCreatedEvent) -> None:print(@@ -193,21 +227,12 @@ def main() -> None:# Buffer stream chunks per worker/task and print once when task completes.stream_buffers: dict[tuple[str, str], list[str]] = {}- def on_worker_stream(- worker_id: str, task_id: str, text: str, _mode: str- ) -> None:- if not text:- return- key = (worker_id, task_id)- stream_buffers.setdefault(key, []).append(text)-workforce = Workforce("Workforce Callbacks Demo",callbacks=[WorkforceLogger('demo-logger'),PrintCallback(stream_buffers),],- stream_callback=on_worker_stream,use_structured_output_handler=True,failure_handling_config=FailureHandlingConfig(enabled_strategies=[]),default_model=model,diff --git a/test/workforce/test_workforce_callbacks.py b/test/workforce/test_workforce_callbacks.pyindex af6eb8b8e..875933a30 100644--- a/test/workforce/test_workforce_callbacks.py+++ b/test/workforce/test_workforce_callbacks.py@@ -18,9 +18,11 @@ import pytestfrom camel.agents import ChatAgentfrom camel.messages import BaseMessagefrom camel.models import ModelFactory+from camel.responses import ChatAgentResponsefrom camel.societies.workforce.events import (AllTasksCompletedEvent,LogEvent,+ StreamChunkEvent,TaskAssignedEvent,TaskCompletedEvent,TaskCreatedEvent,@@ -49,6 +51,9 @@ class _NonMetricsCallback(WorkforceCallback):def log_message(self, event: LogEvent) -> None:pass+ def log_stream_chunk(self, event: StreamChunkEvent) -> None:+ self.events.append(event)+# Task eventsdef log_task_created(self, event: TaskCreatedEvent) -> None:self.events.append(event)@@ -96,6 +101,9 @@ class _MetricsCallback(WorkforceCallback, WorkforceMetrics):def log_message(self, event: LogEvent) -> None:pass+ def log_stream_chunk(self, event: StreamChunkEvent) -> None:+ self.events.append(event)+# WorkforceMetrics interfacedef reset_task_data(self) -> None:self.dump_to_json_called = False@@ -186,6 +194,247 @@ def test_workforce_callback_registration_and_metrics_handling():Workforce("CB Test - Invalid", callbacks=[object()])+def test_workforce_logger_skips_stream_chunks_by_default():+ logger = WorkforceLogger("wf-test")++ logger.log_stream_chunk(+ StreamChunkEvent(+ text="high-volume stream text",+ stream_accumulate_mode="delta",+ task_id="task-1",+ worker_id="worker-1",+ )+ )++ assert logger.log_entries == []+++def test_workforce_logger_can_persist_truncated_stream_chunks():+ logger = WorkforceLogger(+ "wf-test",+ log_stream_chunks=True,+ stream_chunk_text_limit=5,+ )++ logger.log_stream_chunk(+ StreamChunkEvent(+ text="stream text",+ stream_accumulate_mode="delta",+ task_id="task-1",+ worker_id="worker-1",+ metadata={"source": "unit-test"},+ )+ )++ assert len(logger.log_entries) == 1+ entry = logger.log_entries[0]+ assert entry["event_type"] == "stream_chunk"+ assert entry["text"] == "strea"+ assert entry["text_length"] == len("stream text")+ assert entry["text_truncated"] is True+ assert entry["stream_accumulate_mode"] == "delta"+ assert entry["task_id"] == "task-1"+ assert entry["worker_id"] == "worker-1"+ assert entry["metadata"] == {"source": "unit-test"}+++def test_workforce_logger_rejects_negative_stream_chunk_limit():+ with pytest.raises(ValueError, match="stream_chunk_text_limit"):+ WorkforceLogger("wf-test", stream_chunk_text_limit=-1)+++async def test_workforce_callback_receives_internal_stream_chunk_events():+ callback = _NonMetricsCallback()+ workforce = Workforce("CB Stream Test", callbacks=[callback])++ first_chunk = ChatAgentResponse(+ msgs=[+ BaseMessage.make_assistant_message(+ role_name="Assistant",+ content="Hello",+ )+ ],+ terminated=False,+ info={"stream_accumulate_mode": "accumulate"},+ )+ second_chunk = ChatAgentResponse(+ msgs=[+ BaseMessage.make_assistant_message(+ role_name="Assistant",+ content="Hello world",+ )+ ],+ terminated=False,+ info={"stream_accumulate_mode": "accumulate"},+ )++ workforce._on_stream_callback(+ first_chunk,+ )+ workforce._on_stream_callback(+ second_chunk,+ )++ stream_events = [+ event+ for event in callback.events+ if isinstance(event, StreamChunkEvent)+ ]+ assert [+ (+ event.task_id,+ event.worker_id,+ event.text,+ event.stream_accumulate_mode,+ )+ for event in stream_events+ ] == [+ (None, None, "Hello", "accumulate"),+ (None, None, " world", "accumulate"),+ ]+++async def test_internal_stream_progress_resets_after_final_chunk():+ callback = _NonMetricsCallback()+ workforce = Workforce("CB Stream Reset Test", callbacks=[callback])++ first_chunk = ChatAgentResponse(+ msgs=[+ BaseMessage.make_assistant_message(+ role_name="Assistant",+ content="Hello",+ )+ ],+ terminated=False,+ info={"stream_accumulate_mode": "accumulate", "partial": True},+ )+ final_chunk = ChatAgentResponse(+ msgs=[+ BaseMessage.make_assistant_message(+ role_name="Assistant",+ content="Hello world",+ )+ ],+ terminated=False,+ info={"stream_accumulate_mode": "accumulate", "partial": False},+ )+ next_response_chunk = ChatAgentResponse(+ msgs=[+ BaseMessage.make_assistant_message(+ role_name="Assistant",+ content="Hello world again",+ )+ ],+ terminated=False,+ info={"stream_accumulate_mode": "accumulate", "partial": True},+ )++ workforce._on_stream_callback(first_chunk)+ workforce._on_stream_callback(final_chunk)+ workforce._on_stream_callback(next_response_chunk)++ stream_events = [+ event+ for event in callback.events+ if isinstance(event, StreamChunkEvent)+ ]+ assert [event.text for event in stream_events] == [+ "Hello",+ " world",+ "Hello world again",+ ]+++async def test_workforce_callback_receives_worker_stream_chunk_events():+ callback = _NonMetricsCallback()+ workforce = Workforce("CB Worker Stream Test", callbacks=[callback])++ chunk = ChatAgentResponse(+ msgs=[+ BaseMessage.make_assistant_message(+ role_name="Assistant",+ content="partial",+ )+ ],+ terminated=False,+ info={"stream_accumulate_mode": "delta"},+ )++ await workforce._on_worker_stream_chunk(chunk, "worker-1", "task-1")++ stream_events = [+ event+ for event in callback.events+ if isinstance(event, StreamChunkEvent)+ ]+ assert [+ (+ event.task_id,+ event.worker_id,+ event.text,+ event.stream_accumulate_mode,+ )+ for event in stream_events+ ] == [("task-1", "worker-1", "partial", "delta")]+++async def test_worker_stream_progress_resets_after_final_chunk():+ callback = _NonMetricsCallback()+ workforce = Workforce("CB Worker Stream Reset Test", callbacks=[callback])++ first_chunk = ChatAgentResponse(+ msgs=[+ BaseMessage.make_assistant_message(+ role_name="Assistant",+ content="Hello",+ )+ ],+ terminated=False,+ info={"stream_accumulate_mode": "accumulate", "partial": True},+ )+ final_chunk = ChatAgentResponse(+ msgs=[+ BaseMessage.make_assistant_message(+ role_name="Assistant",+ content="Hello world",+ )+ ],+ terminated=False,+ info={"stream_accumulate_mode": "accumulate", "partial": False},+ )+ next_response_chunk = ChatAgentResponse(+ msgs=[+ BaseMessage.make_assistant_message(+ role_name="Assistant",+ content="Hello world again",+ )+ ],+ terminated=False,+ info={"stream_accumulate_mode": "accumulate", "partial": True},+ )++ await workforce._on_worker_stream_chunk(first_chunk, "worker-1", "task-1")+ await workforce._on_worker_stream_chunk(final_chunk, "worker-1", "task-1")+ await workforce._on_worker_stream_chunk(+ next_response_chunk, "worker-1", "task-1"+ )++ stream_events = [+ event+ for event in callback.events+ if isinstance(event, StreamChunkEvent)+ ]+ assert [event.text for event in stream_events] == [+ "Hello",+ " world",+ "Hello world again",+ ]++def assert_event_sequence(events: list[type[WorkforceEvent]], min_worker_count: int):@@ -260,6 +509,7 @@ def assert_event_sequence(allowed_events = {WorkerCreatedEvent,WorkerDeletedEvent,+ StreamChunkEvent,TaskCreatedEvent,TaskDecomposedEvent,TaskAssignedEvent,