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

Auto-update documentation after merge [skip ci]

camel-docs-bot262a1ed37938
diff --git a/docs/mintlify/reference/camel.agents.chat_agent.mdx b/docs/mintlify/reference/camel.agents.chat_agent.mdx
index 42266a854..5805742fd 100644
--- a/docs/mintlify/reference/camel.agents.chat_agent.mdx
+++ b/docs/mintlify/reference/camel.agents.chat_agent.mdx
@@ -897,6 +897,31 @@ response_format was provided.
See Also:
:meth:`asummarize`: Async version for non-blocking LLM calls.
+<a id="camel.agents.chat_agent.ChatAgent._build_conversation_text_from_messages"></a>
+
+### _build_conversation_text_from_messages
+
+```python
+def _build_conversation_text_from_messages(self, messages: List[Any], include_summaries: bool = False):
+```
+
+Build conversation text from messages for summarization.
+
+This is a shared helper method that converts messages to a formatted
+conversation text string, handling tool calls, tool results, and
+regular messages.
+
+**Parameters:**
+
+- **messages** (List[Any]): List of messages to convert.
+- **include_summaries** (bool): Whether to include messages starting with [CONTEXT_SUMMARY]. (default: :obj:`False`)
+
+**Returns:**
+
+ tuple[str, List[str]]: A tuple containing:
+- Formatted conversation text
+- List of user messages extracted from the conversation
+
<a id="camel.agents.chat_agent.ChatAgent.clear_memory"></a>
### clear_memory
diff --git a/docs/mintlify/reference/camel.societies.workforce.utils.mdx b/docs/mintlify/reference/camel.societies.workforce.utils.mdx
index 90b39a23b..852317819 100644
--- a/docs/mintlify/reference/camel.societies.workforce.utils.mdx
+++ b/docs/mintlify/reference/camel.societies.workforce.utils.mdx
@@ -1,5 +1,56 @@
<a id="camel.societies.workforce.utils"></a>
+<a id="camel.societies.workforce.utils.is_generic_role_name"></a>
+
+## is_generic_role_name
+
+```python
+def is_generic_role_name(role_name: str):
+```
+
+Check if a role name is generic and should trigger fallback logic.
+
+Generic role names are common, non-specific identifiers that don't
+provide meaningful information about an agent's actual purpose.
+When a role name is generic, fallback logic should be used to find
+a more specific identifier (e.g., from LLM-generated agent_title
+or description).
+
+**Parameters:**
+
+- **role_name** (str): The role name to check (will be converted to lowercase for case-insensitive comparison).
+
+**Returns:**
+
+ bool: True if the role name is generic, False otherwise.
+
+<a id="camel.societies.workforce.utils.WorkflowMetadata"></a>
+
+## WorkflowMetadata
+
+```python
+class WorkflowMetadata(BaseModel):
+```
+
+Pydantic model for workflow metadata tracking.
+
+This model defines the formal schema for workflow metadata that tracks
+versioning, timestamps, and contextual information about saved workflows.
+Used to maintain workflow history and enable proper version management.
+
+<a id="camel.societies.workforce.utils.WorkflowConfig"></a>
+
+## WorkflowConfig
+
+```python
+class WorkflowConfig(BaseModel):
+```
+
+Configuration for workflow memory management.
+
+Centralizes all workflow-related configuration options to avoid scattered
+settings across multiple files and methods.
+
<a id="camel.societies.workforce.utils.WorkerConf"></a>
## WorkerConf
diff --git a/docs/mintlify/reference/camel.societies.workforce.workflow_memory_manager.mdx b/docs/mintlify/reference/camel.societies.workforce.workflow_memory_manager.mdx
index 78a059976..5c1b2dc9c 100644
--- a/docs/mintlify/reference/camel.societies.workforce.workflow_memory_manager.mdx
+++ b/docs/mintlify/reference/camel.societies.workforce.workflow_memory_manager.mdx
@@ -37,6 +37,8 @@ workflow management concerns from the core worker task processing logic.
- **worker** (ChatAgent): The worker agent that will use workflows.
- **description** (str): Description of the worker's role.
- **context_utility** (Optional[ContextUtility]): Shared context utility for workflow operations. If None, creates a new instance.
+- **role_identifier** (Optional[str]): Role identifier for organizing workflows by role. If provided, workflows will be stored in role-based folders. If None, uses default workforce context.
+- **config** (Optional[WorkflowConfig]): Configuration for workflow management. If None, uses default configuration.
<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager.__init__"></a>
@@ -47,7 +49,9 @@ def __init__(
self,
worker: ChatAgent,
description: str,
- context_utility: Optional[ContextUtility] = None
+ context_utility: Optional[ContextUtility] = None,
+ role_identifier: Optional[str] = None,
+ config: Optional[WorkflowConfig] = None
):
```
@@ -61,6 +65,132 @@ def _get_context_utility(self):
Get context utility with lazy initialization.
+Uses role-based context if role_identifier is set, otherwise falls
+back to default workforce shared context.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._extract_existing_workflow_metadata"></a>
+
+### _extract_existing_workflow_metadata
+
+```python
+def _extract_existing_workflow_metadata(self, file_path: Path):
+```
+
+Extract metadata from an existing workflow file for versioning.
+
+This method reads the metadata section from an existing workflow
+markdown file to retrieve version number and creation timestamp,
+enabling proper version tracking when updating workflows.
+
+**Parameters:**
+
+- **file_path** (Path): Path to the existing workflow file.
+
+**Returns:**
+
+ Optional[WorkflowMetadata]: WorkflowMetadata instance if file
+exists and metadata is successfully parsed, None otherwise.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._try_role_based_loading"></a>
+
+### _try_role_based_loading
+
+```python
+def _try_role_based_loading(
+ self,
+ role_name: str,
+ pattern: Optional[str],
+ max_files_to_load: int,
+ use_smart_selection: bool
+):
+```
+
+Try loading workflows from role-based directory structure.
+
+**Parameters:**
+
+- **role_name** (str): Role name to load workflows from.
+- **pattern** (Optional[str]): Custom search pattern for workflow files.
+- **max_files_to_load** (int): Maximum number of workflow files to load.
+- **use_smart_selection** (bool): Whether to use agent-based selection.
+
+**Returns:**
+
+ bool: True if workflows were successfully loaded, False otherwise.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._try_session_based_loading"></a>
+
+### _try_session_based_loading
+
+```python
+def _try_session_based_loading(
+ self,
+ session_id: str,
+ role_name: str,
+ pattern: Optional[str],
+ max_files_to_load: int,
+ use_smart_selection: bool
+):
+```
+
+Try loading workflows from session-based directory (deprecated).
+
+**Parameters:**
+
+- **session_id** (str): Workforce session ID to load from.
+- **role_name** (str): Role name (for deprecation warning).
+- **pattern** (Optional[str]): Custom search pattern for workflow files.
+- **max_files_to_load** (int): Maximum number of workflow files to load.
+- **use_smart_selection** (bool): Whether to use agent-based selection.
+
+**Returns:**
+
+ bool: True if workflows were successfully loaded, False otherwise.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._session_based_smart_loading"></a>
+
+### _session_based_smart_loading
+
+```python
+def _session_based_smart_loading(self, session_id: str, max_files_to_load: int):
+```
+
+Load workflows from session using smart selection.
+
+**Parameters:**
+
+- **session_id** (str): Session ID to load from.
+- **max_files_to_load** (int): Maximum number of files to load.
+
+**Returns:**
+
+ bool: True if workflows were loaded, False otherwise.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._session_based_pattern_loading"></a>
+
+### _session_based_pattern_loading
+
+```python
+def _session_based_pattern_loading(
+ self,
+ pattern: Optional[str],
+ session_id: str,
+ max_files_to_load: int
+):
+```
+
+Load workflows from session using pattern matching.
+
+**Parameters:**
+
+- **pattern** (Optional[str]): Pattern for file matching.
+- **session_id** (str): Session ID to load from.
+- **max_files_to_load** (int): Maximum number of files to load.
+
+**Returns:**
+
+ bool: True if workflows were loaded, False otherwise.
+
<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager.load_workflows"></a>
### load_workflows
@@ -69,7 +199,7 @@ Get context utility with lazy initialization.
def load_workflows(
self,
pattern: Optional[str] = None,
- max_files_to_load: int = 3,
+ max_files_to_load: Optional[int] = None,
session_id: Optional[str] = None,
use_smart_selection: bool = True
):
@@ -77,15 +207,46 @@ def load_workflows(
Load workflow memories using intelligent agent-based selection.
-This method uses the worker agent to intelligently select the most
-relevant workflows based on workflow information (title, description,
-tags) rather than simple filename pattern matching.
+This method first tries to load workflows from the role-based folder
+structure. If no workflows are found and session_id is provided, falls
+back to session-based loading (deprecated).
**Parameters:**
- **pattern** (Optional[str]): Legacy parameter for backward compatibility. When use_smart_selection=False, uses this pattern for file matching. Ignored when smart selection is enabled.
-- **max_files_to_load** (int): Maximum number of workflow files to load. (default: :obj:`3`)
-- **session_id** (Optional[str]): Specific workforce session ID to load from. If None, searches across all sessions. (default: :obj:`None`)
+- **max_files_to_load** (Optional[int]): Maximum number of workflow files to load. If None, uses config.default_max_files_to_load. (default: :obj:`None`)
+- **session_id** (Optional[str]): Deprecated. Specific workforce session ID to load from using legacy session-based organization. (default: :obj:`None`)
+- **use_smart_selection** (bool): Whether to use agent-based intelligent workflow selection. When True, uses workflow information and LLM to select most relevant workflows. When False, falls back to pattern matching. (default: :obj:`True`)
+
+**Returns:**
+
+ bool: True if workflow memories were successfully loaded, False
+otherwise. Check logs for detailed error messages.
+
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager.load_workflows_by_role"></a>
+
+### load_workflows_by_role
+
+```python
+def load_workflows_by_role(
+ self,
+ role_name: Optional[str] = None,
+ pattern: Optional[str] = None,
+ max_files_to_load: Optional[int] = None,
+ use_smart_selection: bool = True
+):
+```
+
+Load workflow memories from role-based directory structure.
+
+This method loads workflows from the new role-based folder structure:
+workforce_workflows/\{role_name\}/*.md
+
+**Parameters:**
+
+- **role_name** (Optional[str]): Role name to load workflows from. If None, uses the worker's role_name or role_identifier.
+- **pattern** (Optional[str]): Custom search pattern for workflow files. Ignored when use_smart_selection=True.
+- **max_files_to_load** (Optional[int]): Maximum number of workflow files to load. If None, uses config.default_max_files_to_load. (default: :obj:`None`)
- **use_smart_selection** (bool): Whether to use agent-based intelligent workflow selection. When True, uses workflow information and LLM to select most relevant workflows. When False, falls back to pattern matching. (default: :obj:`True`)
**Returns:**
@@ -177,6 +338,11 @@ def _find_workflow_files(self, pattern: Optional[str], session_id: Optional[str]
Find and return sorted workflow files matching the pattern.
+.. note::
+Session-based workflow search will be deprecated in a future
+version. Consider using :meth:`_find_workflow_files_by_role` for
+role-based organization instead.
+
**Parameters:**
- **pattern** (Optional[str]): Custom search pattern for workflow files. If None, uses worker role_name to generate pattern.
@@ -187,6 +353,33 @@ Find and return sorted workflow files matching the pattern.
List[str]: Sorted list of workflow file paths (empty if
validation fails).
+<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._find_workflow_files_by_role"></a>
+
+### _find_workflow_files_by_role
+
+```python
+def _find_workflow_files_by_role(
+ self,
+ role_name: Optional[str] = None,
+ pattern: Optional[str] = None
+):
+```
+
+Find workflow files in role-based directory structure.
+
+This method searches for workflows in the new role-based folder
+structure: workforce_workflows/\{role_name\}/*.md
+
+**Parameters:**
+
+- **role_name** (Optional[str]): Role name to search for. If None, uses the worker's role_name or role_identifier.
+- **pattern** (Optional[str]): Custom search pattern for workflow files. If None, searches for all workflow files in the role directory.
+
+**Returns:**
+
+ List[str]: Sorted list of workflow file paths by modification time
+(most recent first).
+
<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._collect_workflow_contents"></a>
### _collect_workflow_contents
@@ -287,7 +480,7 @@ def _generate_workflow_filename(self):
**Returns:**
str: Sanitized filename without timestamp and without .md
-extension. Format: \{role_name\}_workflow
+extension. Format: \{role_name\}\{workflow_filename_suffix\}
<a id="camel.societies.workforce.workflow_memory_manager.WorkflowMemoryManager._prepare_workflow_prompt"></a>
diff --git a/docs/mintlify/reference/camel.societies.workforce.workforce.mdx b/docs/mintlify/reference/camel.societies.workforce.workforce.mdx
index bc7a6387a..7191c4880 100644
--- a/docs/mintlify/reference/camel.societies.workforce.workforce.mdx
+++ b/docs/mintlify/reference/camel.societies.workforce.workforce.mdx
@@ -153,6 +153,34 @@ unnecessary session folder creation during initialization.
ContextUtility: The shared context utility instance.
+<a id="camel.societies.workforce.workforce.Workforce._get_role_identifier"></a>
+
+### _get_role_identifier
+
+```python
+def _get_role_identifier(
+ self,
+ worker: ChatAgent,
+ description: str,
+ workflow_summary: Optional['WorkflowSummary'] = None
+):
+```
+
+Extract role identifier for organizing workflows.
+
+Uses priority fallback: role_name → agent_title (from
+WorkflowSummary) → sanitized description.
+
+**Parameters:**
+
+- **worker** (ChatAgent): The worker agent to extract role from.
+- **description** (str): Worker description to use as fallback.
+- **workflow_summary** (Optional[WorkflowSummary]): Optional WorkflowSummary object that may contain agent_title field.
+
+**Returns:**
+
+ str: Role identifier for organizing workflows.
+
<a id="camel.societies.workforce.workforce.Workforce._validate_agent_compatibility"></a>
### _validate_agent_compatibility
@@ -989,29 +1017,9 @@ be called when the workforce is not running.
### save_workflow_memories
```python
-def save_workflow_memories(self, session_id: Optional[str] = None):
+def save_workflow_memories(self):
```
-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()
-method.
-Other worker types are skipped.
-
-**Parameters:**
-
-- **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.
diff --git a/docs/mintlify/reference/camel.utils.context_utils.mdx b/docs/mintlify/reference/camel.utils.context_utils.mdx
index 6fbec3ee6..a8e5d5586 100644
--- a/docs/mintlify/reference/camel.utils.context_utils.mdx
+++ b/docs/mintlify/reference/camel.utils.context_utils.mdx
@@ -57,7 +57,8 @@ def __init__(
self,
working_directory: Optional[str] = None,
session_id: Optional[str] = None,
- create_folder: bool = True
+ create_folder: bool = True,
+ use_session_subfolder: bool = True
):
```
@@ -68,6 +69,7 @@ Initialize the ContextUtility.
- **working_directory** (str, optional): The directory path where files will be stored. If not provided, a default directory will be used.
- **session_id** (str, optional): The session ID to use. If provided, this instance will use the same session folder as other instances with the same session_id. If not provided, a new session ID will be generated.
- **create_folder** (bool): Whether to create the session folder immediately. If False, the folder will be created only when needed (e.g., when saving files). Default is True for backward compatibility.
+- **use_session_subfolder** (bool): Whether to append session_id as a subfolder. If False, files are saved directly to working_directory without session subfolder. Use False for role-based organization. Default is True for backward compatibility.
<a id="camel.utils.context_utils.ContextUtility._setup_storage"></a>
@@ -78,7 +80,8 @@ def _setup_storage(
self,
working_directory: Optional[str],
session_id: Optional[str] = None,
- create_folder: bool = True
+ create_folder: bool = True,
+ use_session_subfolder: bool = True
):
```
@@ -321,13 +324,25 @@ Create a session-specific directory.
### get_session_metadata
```python
-def get_session_metadata(self):
+def get_session_metadata(
+ self,
+ workflow_version: int = 1,
+ created_at: Optional[str] = None
+):
```
+Collect comprehensive session information including identifiers,
+timestamps, and directory paths for tracking and reference.
+
+**Parameters:**
+
+- **workflow_version** (int): Version number of the workflow. Defaults to 1 for new workflows. (default: :obj:`1`)
+- **created_at** (Optional[str]): ISO timestamp when workflow was first created. If None, uses current timestamp for new workflows. (default: :obj:`None`)
+
**Returns:**
Dict[str, Any]: Session metadata including ID, timestamp,
-directory.
+directory, version, and update timestamp.
<a id="camel.utils.context_utils.ContextUtility.list_sessions"></a>
@@ -514,6 +529,11 @@ def get_workforce_shared(cls, session_id: Optional[str] = None):
Get or create shared workforce context utility with lazy init.
+.. note::
+Session-based workflow storage will be deprecated in a future
+version. Consider using :meth:`get_workforce_shared_by_role` for
+role-based organization instead.
+
This method provides a centralized way to access shared context
utilities for workforce workflows, ensuring all workforce components
use the same session directory.
@@ -526,6 +546,27 @@ use the same session directory.
ContextUtility: Shared context utility instance for workforce.
+<a id="camel.utils.context_utils.ContextUtility.get_workforce_shared_by_role"></a>
+
+### get_workforce_shared_by_role
+
+```python
+def get_workforce_shared_by_role(cls, role_identifier: str):
+```
+
+Get or create shared workforce context utility based on role.
+
+This method provides role-based context utilities for workforce
+workflows, organizing workflows by agent role instead of session ID.
+
+**Parameters:**
+
+- **role_identifier** (str): Role identifier (e.g., role_name or agent_title). Will be sanitized for filesystem use.
+
+**Returns:**
+
+ ContextUtility: Shared context utility instance for the role.
+
<a id="camel.utils.context_utils.ContextUtility.reset_shared_sessions"></a>
### reset_shared_sessions