Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

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.py
index 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.py
index 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.py
index 42c7bab93..132a1971f 100644
--- a/camel/societies/workforce/workforce_callback.py
+++ b/camel/societies/workforce/workforce_callback.py
@@ -21,6 +21,7 @@ from colorama import Fore
from .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
+
@abstractmethod
def log_task_created(
self,
diff --git a/camel/societies/workforce/workforce_logger.py b/camel/societies/workforce/workforce_logger.py
index 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_limit
self.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.py
index 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 time
from camel.agents import ChatAgent
from camel.configs import ChatGPTConfig
@@ -31,6 +32,7 @@ from camel.societies.workforce import FailureHandlingConfig
from 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.py
index af6eb8b8e..875933a30 100644
--- a/test/workforce/test_workforce_callbacks.py
+++ b/test/workforce/test_workforce_callbacks.py
@@ -18,9 +18,11 @@ import pytest
from camel.agents import ChatAgent
from camel.messages import BaseMessage
from camel.models import ModelFactory
+from camel.responses import ChatAgentResponse
from 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 events
def 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 interface
def 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,