🐫 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
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.mdxindex 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_memorydiff --git a/docs/mintlify/reference/camel.societies.workforce.utils.mdx b/docs/mintlify/reference/camel.societies.workforce.utils.mdxindex 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>## WorkerConfdiff --git a/docs/mintlify/reference/camel.societies.workforce.workflow_memory_manager.mdx b/docs/mintlify/reference/camel.societies.workforce.workflow_memory_manager.mdxindex 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 ifvalidation 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.mdxindex 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.mdxindex 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 contextutilities for workforce workflows, ensuring all workforce componentsuse 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