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

enhance: Support async summarize in ChatAgent for faster Workforce sa… (#3299)

Wendong-Fan6126e80532b5
diff --git a/camel/agents/chat_agent.py b/camel/agents/chat_agent.py
index 077a7c11c..df7f9157f 100644
--- a/camel/agents/chat_agent.py
+++ b/camel/agents/chat_agent.py
@@ -1077,6 +1077,10 @@ class ChatAgent(BaseAgent):
r"""Summarize the agent's current conversation context and persist it
to a markdown file.
+ .. deprecated:: 0.2.80
+ Use :meth:`asummarize` for async/await support and better
+ performance in parallel summarization workflows.
+
Args:
filename (Optional[str]): The base filename (without extension) to
use for the markdown file. Defaults to a timestamped name when
@@ -1096,7 +1100,18 @@ class ChatAgent(BaseAgent):
Dict[str, Any]: A dictionary containing the summary text, file
path, status message, and optionally structured_summary if
response_format was provided.
+
+ See Also:
+ :meth:`asummarize`: Async version for non-blocking LLM calls.
"""
+ import warnings
+
+ warnings.warn(
+ "summarize() is synchronous. Consider using asummarize() "
+ "for async/await support and better performance.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
result: Dict[str, Any] = {
"summary": "",
@@ -1319,6 +1334,271 @@ class ChatAgent(BaseAgent):
result["status"] = error_message
return result
+ async def asummarize(
+ self,
+ filename: Optional[str] = None,
+ summary_prompt: Optional[str] = None,
+ response_format: Optional[Type[BaseModel]] = None,
+ working_directory: Optional[Union[str, Path]] = None,
+ ) -> Dict[str, Any]:
+ r"""Asynchronously summarize the agent's current conversation context
+ and persist it to a markdown file.
+
+ This is the async version of summarize() that uses astep() for
+ non-blocking LLM calls, enabling parallel summarization of multiple
+ agents.
+
+ Args:
+ filename (Optional[str]): The base filename (without extension) to
+ use for the markdown file. Defaults to a timestamped name when
+ not provided.
+ summary_prompt (Optional[str]): Custom prompt for the summarizer.
+ When omitted, a default prompt highlighting key decisions,
+ action items, and open questions is used.
+ response_format (Optional[Type[BaseModel]]): A Pydantic model
+ defining the expected structure of the response. If provided,
+ the summary will be generated as structured output and included
+ in the result.
+ working_directory (Optional[str|Path]): Optional directory to save
+ the markdown summary file. If provided, overrides the default
+ directory used by ContextUtility.
+
+ Returns:
+ Dict[str, Any]: A dictionary containing the summary text, file
+ path, status message, and optionally structured_summary if
+ response_format was provided.
+ """
+
+ result: Dict[str, Any] = {
+ "summary": "",
+ "file_path": None,
+ "status": "",
+ }
+
+ try:
+ # Use external context if set, otherwise create local one
+ if self._context_utility is None:
+ if working_directory is not None:
+ self._context_utility = ContextUtility(
+ working_directory=str(working_directory)
+ )
+ else:
+ self._context_utility = ContextUtility()
+ context_util = self._context_utility
+
+ # Get conversation directly from agent's memory
+ messages, _ = self.memory.get_context()
+
+ if not messages:
+ status_message = (
+ "No conversation context available to summarize."
+ )
+ result["status"] = status_message
+ return result
+
+ # Convert messages to conversation text
+ conversation_lines = []
+ for message in messages:
+ role = message.get('role', 'unknown')
+ content = message.get('content', '')
+
+ # Handle tool call messages (assistant calling tools)
+ tool_calls = message.get('tool_calls')
+ if tool_calls and isinstance(tool_calls, (list, tuple)):
+ for tool_call in tool_calls:
+ # Handle both dict and object formats
+ if isinstance(tool_call, dict):
+ func_name = tool_call.get('function', {}).get(
+ 'name', 'unknown_tool'
+ )
+ func_args_str = tool_call.get('function', {}).get(
+ 'arguments', '{}'
+ )
+ else:
+ # Handle object format (Pydantic or similar)
+ func_name = getattr(
+ getattr(tool_call, 'function', None),
+ 'name',
+ 'unknown_tool',
+ )
+ func_args_str = getattr(
+ getattr(tool_call, 'function', None),
+ 'arguments',
+ '{}',
+ )
+
+ # Parse and format arguments for readability
+ try:
+ import json
+
+ args_dict = json.loads(func_args_str)
+ args_formatted = ', '.join(
+ f"{k}={v}" for k, v in args_dict.items()
+ )
+ except (json.JSONDecodeError, ValueError, TypeError):
+ args_formatted = func_args_str
+
+ conversation_lines.append(
+ f"[TOOL CALL] {func_name}({args_formatted})"
+ )
+
+ # Handle tool response messages
+ elif role == 'tool':
+ tool_name = message.get('name', 'unknown_tool')
+ if not content:
+ content = str(message.get('content', ''))
+ conversation_lines.append(
+ f"[TOOL RESULT] {tool_name} → {content}"
+ )
+
+ # Handle regular content messages (user/assistant/system)
+ elif content:
+ conversation_lines.append(f"{role}: {content}")
+
+ conversation_text = "\n".join(conversation_lines).strip()
+
+ if not conversation_text:
+ status_message = (
+ "Conversation context is empty; skipping summary."
+ )
+ result["status"] = status_message
+ return result
+
+ if self._context_summary_agent is None:
+ self._context_summary_agent = ChatAgent(
+ system_message=(
+ "You are a helpful assistant that summarizes "
+ "conversations"
+ ),
+ model=self.model_backend,
+ agent_id=f"{self.agent_id}_context_summarizer",
+ )
+ else:
+ self._context_summary_agent.reset()
+
+ if summary_prompt:
+ prompt_text = (
+ f"{summary_prompt.rstrip()}\n\n"
+ f"AGENT CONVERSATION TO BE SUMMARIZED:\n"
+ f"{conversation_text}"
+ )
+ else:
+ prompt_text = (
+ "Summarize the context information in concise markdown "
+ "bullet points highlighting key decisions, action items.\n"
+ f"Context information:\n{conversation_text}"
+ )
+
+ try:
+ # Use structured output if response_format is provided
+ if response_format:
+ response = await self._context_summary_agent.astep(
+ prompt_text, response_format=response_format
+ )
+ else:
+ response = await self._context_summary_agent.astep(
+ prompt_text
+ )
+
+ # Handle streaming response
+ if isinstance(response, AsyncStreamingChatAgentResponse):
+ # Collect final response
+ final_response = await response
+ response = final_response
+
+ except Exception as step_exc:
+ error_message = (
+ f"Failed to generate summary using model: {step_exc}"
+ )
+ logger.error(error_message)
+ result["status"] = error_message
+ return result
+
+ if not response.msgs:
+ status_message = (
+ "Failed to generate summary from model response."
+ )
+ result["status"] = status_message
+ return result
+
+ summary_content = response.msgs[-1].content.strip()
+ if not summary_content:
+ status_message = "Generated summary is empty."
+ result["status"] = status_message
+ return result
+
+ # handle structured output if response_format was provided
+ structured_output = None
+ if response_format and response.msgs[-1].parsed:
+ structured_output = response.msgs[-1].parsed
+
+ # determine filename: use provided filename, or extract from
+ # structured output, or generate timestamp
+ if filename:
+ base_filename = filename
+ elif structured_output and hasattr(
+ structured_output, 'task_title'
+ ):
+ # use task_title from structured output for filename
+ task_title = structured_output.task_title
+ clean_title = ContextUtility.sanitize_workflow_filename(
+ task_title
+ )
+ base_filename = (
+ f"{clean_title}_workflow" if clean_title else "workflow"
+ )
+ else:
+ base_filename = f"context_summary_{datetime.now().strftime('%Y%m%d_%H%M%S')}" # noqa: E501
+
+ base_filename = Path(base_filename).with_suffix("").name
+
+ metadata = context_util.get_session_metadata()
+ metadata.update(
+ {
+ "agent_id": self.agent_id,
+ "message_count": len(messages),
+ }
+ )
+
+ # convert structured output to custom markdown if present
+ if structured_output:
+ # convert structured output to custom markdown
+ summary_content = context_util.structured_output_to_markdown(
+ structured_data=structured_output, metadata=metadata
+ )
+
+ # Save the markdown (either custom structured or default)
+ save_status = context_util.save_markdown_file(
+ base_filename,
+ summary_content,
+ title="Conversation Summary"
+ if not structured_output
+ else None,
+ metadata=metadata if not structured_output else None,
+ )
+
+ file_path = (
+ context_util.get_working_directory() / f"{base_filename}.md"
+ )
+
+ # Prepare result dictionary
+ result_dict = {
+ "summary": summary_content,
+ "file_path": str(file_path),
+ "status": save_status,
+ "structured_summary": structured_output,
+ }
+
+ result.update(result_dict)
+ logger.info("Conversation summary saved to %s", file_path)
+ return result
+
+ except Exception as exc:
+ error_message = f"Failed to summarize conversation context: {exc}"
+ logger.error(error_message)
+ result["status"] = error_message
+ return result
+
def clear_memory(self) -> None:
r"""Clear the agent's memory and reset to initial state.
diff --git a/camel/societies/workforce/single_agent_worker.py b/camel/societies/workforce/single_agent_worker.py
index 327a4d17d..d1181346f 100644
--- a/camel/societies/workforce/single_agent_worker.py
+++ b/camel/societies/workforce/single_agent_worker.py
@@ -581,6 +581,10 @@ class SingleAgentWorker(Worker):
r"""Save the worker's current workflow memories using agent
summarization.
+ .. deprecated:: 0.2.80
+ Use :meth:`save_workflow_memories_async` for async/await support
+ and better integration with parallel workflow saving.
+
This method generates a workflow summary from the worker agent's
conversation history and saves it to a markdown file. The filename
is based on either the worker's explicit role_name or the generated
@@ -592,7 +596,19 @@ class SingleAgentWorker(Worker):
- summary (str): Generated workflow summary
- file_path (str): Path to saved file
- worker_description (str): Worker description used
+
+ See Also:
+ :meth:`save_workflow_memories_async`: Async version for better
+ performance in parallel workflows.
"""
+ import warnings
+
+ warnings.warn(
+ "save_workflow_memories() is synchronous. Consider using "
+ "save_workflow_memories_async() for async/await support.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
try:
# validate requirements
validation_error = self._validate_workflow_save_requirements()
@@ -655,6 +671,84 @@ class SingleAgentWorker(Worker):
"message": f"Failed to save workflow memories: {e!s}",
}
+ async def save_workflow_memories_async(self) -> Dict[str, Any]:
+ r"""Asynchronously save the worker's current workflow memories using
+ agent summarization.
+
+ This is the async version of save_workflow_memories() that uses
+ asummarize() for non-blocking LLM calls, enabling parallel
+ summarization of multiple workers.
+
+ Returns:
+ Dict[str, Any]: Result dictionary with keys:
+ - status (str): "success" or "error"
+ - summary (str): Generated workflow summary
+ - file_path (str): Path to saved file
+ - worker_description (str): Worker description used
+ """
+ try:
+ # validate requirements
+ validation_error = self._validate_workflow_save_requirements()
+ if validation_error:
+ return validation_error
+
+ # setup context utility and agent
+ context_util = self._get_context_utility()
+ self.worker.set_context_utility(context_util)
+
+ # prepare workflow summarization components
+ structured_prompt = self._prepare_workflow_prompt()
+ agent_to_summarize = self._select_agent_for_summarization(
+ context_util
+ )
+
+ # check if we should use role_name or let summarize extract
+ # task_title
+ role_name = getattr(self.worker, 'role_name', 'assistant')
+ use_role_name_for_filename = role_name.lower() not in {
+ 'assistant',
+ 'agent',
+ 'user',
+ 'system',
+ }
+
+ # generate and save workflow summary
+ # if role_name is explicit, use it for filename
+ # if role_name is generic, pass none to let summarize use
+ # task_title
+ filename = (
+ self._generate_workflow_filename()
+ if use_role_name_for_filename
+ else None
+ )
+
+ # **KEY CHANGE**: Using asummarize() instead of summarize()
+ result = await agent_to_summarize.asummarize(
+ filename=filename,
+ summary_prompt=structured_prompt,
+ response_format=WorkflowSummary,
+ )
+
+ # add worker metadata and cleanup
+ result["worker_description"] = self.description
+ if self._conversation_accumulator is not None:
+ logger.info(
+ "Cleaning up conversation accumulator after workflow "
+ "summarization"
+ )
+ self._conversation_accumulator = None
+
+ return result
+
+ except Exception as e:
+ return {
+ "status": "error",
+ "summary": "",
+ "file_path": None,
+ "worker_description": self.description,
+ "message": f"Failed to save workflow memories: {e!s}",
+ }
+
def load_workflow_memories(
self,
pattern: Optional[str] = None,
diff --git a/camel/societies/workforce/workforce.py b/camel/societies/workforce/workforce.py
index 431166079..73a5e23ed 100644
--- a/camel/societies/workforce/workforce.py
+++ b/camel/societies/workforce/workforce.py
@@ -2146,6 +2146,13 @@ class Workforce(BaseNode):
r"""Save workflow memories for all SingleAgentWorker instances in the
workforce.
+ .. deprecated:: 0.2.80
+ This synchronous method processes workers sequentially, which can
+ be slow for multiple agents. Use
+ :meth:`save_workflow_memories_async`
+ instead for parallel processing and significantly better
+ performance.
+
This method iterates through all child workers and triggers workflow
saving for SingleAgentWorker instances using their
save_workflow_memories()
@@ -2175,7 +2182,26 @@ class Workforce(BaseNode):
>>> results = workforce.save_workflow_memories(
... session_id="project_123"
... )
+
+ Note:
+ For better performance with multiple workers, use the async
+ version::
+
+ results = await workforce.save_workflow_memories_async()
+
+ See Also:
+ :meth:`save_workflow_memories_async`: Async version with parallel
+ processing for significantly better performance.
"""
+ import warnings
+
+ warnings.warn(
+ "save_workflow_memories() is slow for multiple workers. "
+ "Consider using save_workflow_memories_async() for parallel "
+ "processing and ~4x faster performance.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
results = {}
# Get or create shared context utility for this save operation
@@ -2214,6 +2240,116 @@ class Workforce(BaseNode):
logger.info(f"Workflow save completed for {len(results)} workers")
return results
+ async def save_workflow_memories_async(
+ self,
+ session_id: Optional[str] = None,
+ ) -> Dict[str, str]:
+ r"""Asynchronously save workflow memories for all SingleAgentWorker
+ instances in the workforce.
+
+ This is the async version of save_workflow_memories() that parallelizes
+ LLM summarization calls across all workers using asyncio.gather(),
+ significantly reducing total save time.
+
+ This method iterates through all child workers and triggers workflow
+ saving for SingleAgentWorker instances using their
+ save_workflow_memories_async() method in parallel.
+ Other worker types are skipped.
+
+ Args:
+ session_id (Optional[str]): Custom session ID to use for saving
+ workflows. If None, auto-generates a timestamped session ID.
+ Useful for organizing workflows by project or context.
+ (default: :obj:`None`)
+
+ Returns:
+ Dict[str, str]: Dictionary mapping worker node IDs to save results.
+ Values are either file paths (success) or error messages
+ (failure).
+
+ Example:
+ >>> workforce = Workforce("My Team")
+ >>> # ... add workers and process tasks ...
+ >>> # save with parallel summarization (faster)
+ >>> results = await workforce.save_workflow_memories_async()
+ >>> print(results)
+ {'worker_123': '/path/to/developer_agent_workflow.md',
+ 'worker_456': '/path/to/search_agent_workflow.md',
+ 'worker_789': '/path/to/document_agent_workflow.md'}
+ """
+ import asyncio
+
+ results = {}
+
+ # Get or create shared context utility for this save operation
+ shared_context_utility = self._get_or_create_shared_context_utility(
+ session_id=session_id
+ )
+
+ # Prepare tasks for parallel execution
+ async def save_single_worker(
+ child: BaseNode,
+ ) -> tuple[str, str]:
+ """Save workflow for a single worker, then return (node_id,
+ result)."""
+ if isinstance(child, SingleAgentWorker):
+ try:
+ # Set the shared context utility for this operation
+ child._shared_context_utility = shared_context_utility
+ child.worker.set_context_utility(shared_context_utility)
+
+ result = await child.save_workflow_memories_async()
+ if result.get("status") == "success":
+ return (
+ child.node_id,
+ result.get("file_path", "unknown_path"),
+ )
+ else:
+ # Error: check if there's a separate message field,
+ # otherwise use the status itself
+ error_msg = result.get(
+ "message", result.get("status", "Unknown error")
+ )
+ return (child.node_id, f"error: {error_msg}")
+
+ except Exception as e:
+ return (child.node_id, f"error: {e!s}")
+ else:
+ # Skip non-SingleAgentWorker types
+ return (
+ child.node_id,
+ f"skipped: {type(child).__name__} not supported",
+ )
+
+ # Create tasks for all workers
+ tasks = [save_single_worker(child) for child in self._children]
+
+ # Execute all tasks in parallel using asyncio.gather()
+ parallel_results = await asyncio.gather(*tasks, return_exceptions=True)
+
+ # Process results
+ for result in parallel_results:
+ if isinstance(result, Exception):
+ # Handle any unexpected exceptions
+ logger.error(
+ f"Unexpected error during workflow save: {result}"
+ )
+ results["unknown"] = f"error: {result!s}"
+ elif isinstance(result, tuple) and len(result) == 2:
+ # Successfully got (node_id, save_result) tuple
+ node_id, save_result = result
+ results[node_id] = save_result
+ else:
+ # Unexpected result format
+ logger.error(f"Unexpected result format: {result}")
+ results["unknown"] = "error: unexpected result format"
+
+ logger.info(
+ f"Workflow save completed for {len(results)} workers "
+ f"(parallelized)"
+ )
+ return results
+
def load_workflow_memories(
self,
max_files_to_load: int = 3,
diff --git a/examples/workforce/workforce_workflow_memory_example.py b/examples/workforce/workforce_workflow_memory_example.py
index ef7051b34..9c73fe1b3 100644
--- a/examples/workforce/workforce_workflow_memory_example.py
+++ b/examples/workforce/workforce_workflow_memory_example.py
@@ -14,6 +14,7 @@
# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import asyncio
import os
from dotenv import load_dotenv
@@ -83,11 +84,12 @@ def create_writer_agent() -> ChatAgent:
return ChatAgent(system_message=writer_msg, model=model)
-def demonstrate_first_session():
+async def demonstrate_first_session():
r"""Demonstrate first workforce session with workflow saving.
Creates a workforce with math and writer agents, processes tasks,
- and saves the resulting workflows for future use.
+ and saves the resulting workflows for future use using async parallel
+ summarization.
Returns:
Dict[str, str]: Results of the workflow saving operation.
@@ -127,17 +129,17 @@ def demonstrate_first_session():
for task in tasks:
try:
- workforce.process_task(task)
+ await workforce.process_task_async(task)
except Exception as e:
logger.warning(f"Failed to process task {task.id}: {e}")
- # Save workflows after completing tasks
- saved_workflows = workforce.save_workflow_memories()
+ # Save workflows after completing tasks using async parallel version
+ saved_workflows = await workforce.save_workflow_memories_async()
return saved_workflows
-def demonstrate_second_session():
+async def demonstrate_second_session():
r"""Demonstrate second workforce session with workflow loading.
Creates a new workforce instance, loads previously saved workflows,
@@ -184,7 +186,7 @@ def demonstrate_second_session():
for task in new_tasks:
try:
- workforce.process_task(task)
+ await workforce.process_task_async(task)
except Exception as e:
logger.warning(f"Failed to process task {task.id}: {e}")
@@ -228,14 +230,14 @@ def demonstrate_workflow_file_management() -> None:
logger.info("No workflow directory found yet")
-def main() -> None:
+async def main() -> None:
try:
# First session to execute tasks and save workflows
- saved_results = demonstrate_first_session()
+ saved_results = await demonstrate_first_session()
print(f"Workflow save results: {saved_results}")
# Second session to load workflows and execute new tasks
- loaded_results = demonstrate_second_session()
+ loaded_results = await demonstrate_second_session()
print(f"Workflow load results: {loaded_results}")
except Exception as e:
@@ -244,7 +246,7 @@ def main() -> None:
if __name__ == "__main__":
- main()
+ asyncio.run(main())
"""
===============================================================================