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: more robust workforce and update related modules (#2747)

Wendong-Fandedea076aed0
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index d2084ca56..70fc15565 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -26,7 +26,7 @@ body:
attributes:
label: What version of camel are you using?
description: Run command `python3 -c 'print(__import__("camel").__version__)'` in your shell and paste the output here.
- placeholder: E.g., 0.2.70
+ placeholder: E.g., 0.2.71a1
validations:
required: true
diff --git a/camel/__init__.py b/camel/__init__.py
index fc76c12c8..02d97c12d 100644
--- a/camel/__init__.py
+++ b/camel/__init__.py
@@ -14,7 +14,7 @@
from camel.logger import disable_logging, enable_logging, set_log_level
-__version__ = '0.2.70'
+__version__ = '0.2.71a1'
__all__ = [
'__version__',
diff --git a/camel/societies/workforce/role_playing_worker.py b/camel/societies/workforce/role_playing_worker.py
index 9180466da..7e844ca22 100644
--- a/camel/societies/workforce/role_playing_worker.py
+++ b/camel/societies/workforce/role_playing_worker.py
@@ -27,7 +27,7 @@ from camel.societies.workforce.prompts import (
)
from camel.societies.workforce.utils import TaskResult
from camel.societies.workforce.worker import Worker
-from camel.tasks.task import Task, TaskState, validate_task_content
+from camel.tasks.task import Task, TaskState, is_task_result_insufficient
class RolePlayingWorker(Worker):
@@ -178,14 +178,14 @@ class RolePlayingWorker(Worker):
result_dict = json.loads(response.msg.content)
task_result = TaskResult(**result_dict)
- if not validate_task_content(task_result.content, task.id):
+ task.result = task_result.content
+
+ if is_task_result_insufficient(task):
print(
f"{Fore.RED}Task {task.id}: Content validation failed - "
f"task marked as failed{Fore.RESET}"
)
return TaskState.FAILED
- task.result = task_result.content
-
print(f"Task result: {task.result}\n")
return TaskState.DONE
diff --git a/camel/societies/workforce/single_agent_worker.py b/camel/societies/workforce/single_agent_worker.py
index 6ce56eda9..caa6af2b5 100644
--- a/camel/societies/workforce/single_agent_worker.py
+++ b/camel/societies/workforce/single_agent_worker.py
@@ -26,7 +26,7 @@ from camel.agents import ChatAgent
from camel.societies.workforce.prompts import PROCESS_TASK_PROMPT
from camel.societies.workforce.utils import TaskResult
from camel.societies.workforce.worker import Worker
-from camel.tasks.task import Task, TaskState, validate_task_content
+from camel.tasks.task import Task, TaskState, is_task_result_insufficient
class AgentPool:
@@ -352,14 +352,14 @@ class SingleAgentWorker(Worker):
if task_result.failed:
return TaskState.FAILED
- if not validate_task_content(task_result.content, task.id):
+ task.result = task_result.content
+
+ if is_task_result_insufficient(task):
print(
f"{Fore.RED}Task {task.id}: Content validation failed - "
f"task marked as failed{Fore.RESET}"
)
return TaskState.FAILED
-
- task.result = task_result.content
return TaskState.DONE
async def _listen_to_channel(self):
diff --git a/camel/societies/workforce/workforce.py b/camel/societies/workforce/workforce.py
index fe1e42c29..ffbca232e 100644
--- a/camel/societies/workforce/workforce.py
+++ b/camel/societies/workforce/workforce.py
@@ -43,7 +43,12 @@ from camel.societies.workforce.utils import (
check_if_running,
)
from camel.societies.workforce.worker import Worker
-from camel.tasks.task import Task, TaskState, validate_task_content
+from camel.tasks.task import (
+ Task,
+ TaskState,
+ is_task_result_insufficient,
+ validate_task_content,
+)
from camel.toolkits import (
CodeExecutionToolkit,
SearchToolkit,
@@ -57,6 +62,12 @@ from .workforce_logger import WorkforceLogger
logger = get_logger(__name__)
+# Constants for configuration values
+MAX_TASK_RETRIES = 3
+MAX_PENDING_TASKS_LIMIT = 20
+TASK_TIMEOUT_SECONDS = 180.0
+DEFAULT_WORKER_POOL_SIZE = 10
+
class WorkforceState(Enum):
r"""Workforce execution state for human intervention support."""
@@ -216,6 +227,7 @@ class Workforce(BaseNode):
self._completed_tasks: List[Task] = []
self._loop: Optional[asyncio.AbstractEventLoop] = None
self._main_task_future: Optional[asyncio.Future] = None
+ self._cleanup_task: Optional[asyncio.Task] = None
# Snapshot throttle support
self._last_snapshot_time: float = 0.0
# Minimum seconds between automatic snapshots
@@ -517,6 +529,15 @@ class Workforce(BaseNode):
except Exception as e:
logger.warning(f"Error synchronizing shared memory: {e}")
+ def _cleanup_task_tracking(self, task_id: str) -> None:
+ r"""Clean up tracking data for a task to prevent memory leaks.
+
+ Args:
+ task_id (str): The ID of the task to clean up.
+ """
+ if task_id in self._task_start_times:
+ del self._task_start_times[task_id]
+
def _decompose_task(self, task: Task) -> List[Task]:
r"""Decompose the task into subtasks. This method will also set the
relationship between the task and its subtasks.
@@ -1104,7 +1125,7 @@ class Workforce(BaseNode):
self,
description: str,
worker: ChatAgent,
- pool_max_size: int = 10,
+ pool_max_size: int = DEFAULT_WORKER_POOL_SIZE,
) -> Workforce:
r"""Add a worker node to the workforce that uses a single agent.
@@ -1233,7 +1254,7 @@ class Workforce(BaseNode):
except RuntimeError:
asyncio.run(self._async_reset())
- if hasattr(self, 'logger') and self.metrics_logger is not None:
+ if hasattr(self, 'metrics_logger') and self.metrics_logger is not None:
self.metrics_logger.reset_task_data()
else:
self.metrics_logger = WorkforceLogger(workforce_id=self.node_id)
@@ -1516,12 +1537,26 @@ class Workforce(BaseNode):
# Record the start time when a task is posted
self._task_start_times[task.id] = time.time()
+ task.assigned_worker_id = assignee_id
+
if self.metrics_logger:
self.metrics_logger.log_task_started(
task_id=task.id, worker_id=assignee_id
)
- self._in_flight_tasks += 1
- await self._channel.post_task(task, self.node_id, assignee_id)
+
+ try:
+ self._in_flight_tasks += 1
+ await self._channel.post_task(task, self.node_id, assignee_id)
+ logger.debug(
+ f"Posted task {task.id} to {assignee_id}. "
+ f"In-flight tasks: {self._in_flight_tasks}"
+ )
+ except Exception as e:
+ # Decrement counter if posting failed
+ self._in_flight_tasks -= 1
+ logger.error(
+ f"Failed to post task {task.id} to {assignee_id}: {e}"
+ )
async def _post_dependency(self, dependency: Task) -> None:
await self._channel.post_dependency(dependency, self.node_id)
@@ -1580,7 +1615,7 @@ class Workforce(BaseNode):
new_node = SingleAgentWorker(
description=new_node_conf.description,
worker=new_agent,
- pool_max_size=10, # TODO: make this configurable
+ pool_max_size=DEFAULT_WORKER_POOL_SIZE,
)
new_node.set_channel(self._channel)
@@ -1623,7 +1658,7 @@ class Workforce(BaseNode):
return ChatAgent(worker_sys_msg, model=model, tools=function_list) # type: ignore[arg-type]
- async def _get_returned_task(self) -> Task:
+ async def _get_returned_task(self) -> Optional[Task]:
r"""Get the task that's published by this node and just get returned
from the assignee. Includes timeout handling to prevent indefinite
waiting.
@@ -1632,17 +1667,28 @@ class Workforce(BaseNode):
# Add timeout to prevent indefinite waiting
return await asyncio.wait_for(
self._channel.get_returned_task_by_publisher(self.node_id),
- timeout=180.0, # 3 minute timeout
+ timeout=TASK_TIMEOUT_SECONDS,
)
- except asyncio.TimeoutError:
- logger.warning(
- f"Timeout waiting for returned task in "
+ except Exception as e:
+ # Decrement in-flight counter to prevent hanging
+ if self._in_flight_tasks > 0:
+ self._in_flight_tasks -= 1
+
+ error_msg = (
+ f"Error getting returned task {e} in "
f"workforce {self.node_id}. "
- f"This may indicate an issue with async tool execution. "
f"Current pending tasks: {len(self._pending_tasks)}, "
f"In-flight tasks: {self._in_flight_tasks}"
)
- raise
+ logger.warning(error_msg)
+
+ if self._pending_tasks and self._assignees:
+ for task in self._pending_tasks:
+ if task.id in self._assignees:
+ # Mark this real task as failed
+ task.set_state(TaskState.FAILED)
+ return task
+ return None
async def _post_ready_tasks(self) -> None:
r"""Checks for unassigned tasks, assigns them, and then posts any
@@ -1682,6 +1728,9 @@ class Workforce(BaseNode):
# Step 2: Iterate through all pending tasks and post those that are
# ready
posted_tasks = []
+ # Pre-compute completed task IDs set for O(1) lookups
+ completed_task_ids = {t.id for t in self._completed_tasks}
+
for task in self._pending_tasks:
# A task must be assigned to be considered for posting
if task.id in self._task_dependencies:
@@ -1689,8 +1738,7 @@ class Workforce(BaseNode):
# Check if all dependencies for this task are in the completed
# set
if all(
- dep_id in {t.id for t in self._completed_tasks}
- for dep_id in dependencies
+ dep_id in completed_task_ids for dep_id in dependencies
):
assignee_id = self._assignees[task.id]
logger.debug(
@@ -1712,17 +1760,67 @@ class Workforce(BaseNode):
async def _handle_failed_task(self, task: Task) -> bool:
task.failure_count += 1
+ # Determine detailed failure information
+ if is_task_result_insufficient(task):
+ failure_reason = "Worker returned unhelpful "
+ f"response: {task.result[:100] if task.result else ''}..."
+ else:
+ failure_reason = "Task marked as failed despite "
+ f"having result: {(task.result or '')[:100]}..."
+
+ # Add context about the worker and task
+ worker_id = task.assigned_worker_id or "unknown"
+ worker_info = f" (assigned to worker: {worker_id})"
+
+ detailed_error = f"{failure_reason}{worker_info}"
+
+ logger.error(
+ f"Task {task.id} failed (attempt "
+ f"{task.failure_count}/3): {detailed_error}"
+ )
+
if self.metrics_logger:
- worker_id = self._assignees.get(task.id)
self.metrics_logger.log_task_failed(
task_id=task.id,
worker_id=worker_id,
- error_message=task.result or "Task execution failed",
+ error_message=detailed_error,
error_type="TaskFailure",
- metadata={'failure_count': task.failure_count},
+ metadata={
+ 'failure_count': task.failure_count,
+ 'task_content': task.content,
+ 'result_length': len(task.result) if task.result else 0,
+ },
)
- if task.failure_count > 3:
+ # Check for immediate halt conditions - return immediately if we
+ # should halt
+ if task.failure_count >= MAX_TASK_RETRIES:
+ logger.error(
+ f"Task {task.id} has exceeded maximum retry attempts "
+ f"({MAX_TASK_RETRIES}). Final failure "
+ f"reason: {detailed_error}. "
+ f"Task content: '{task.content[:100]}...'"
+ )
+ self._cleanup_task_tracking(task.id)
+ # Mark task as completed for dependency tracking before halting
+ self._completed_tasks.append(task)
+ if task.id in self._assignees:
+ await self._channel.archive_task(task.id)
+ return True
+
+ # If too many tasks are failing rapidly, also halt to prevent infinite
+ # loops
+ if len(self._pending_tasks) > MAX_PENDING_TASKS_LIMIT:
+ logger.error(
+ f"Too many pending tasks ({len(self._pending_tasks)} > "
+ f"{MAX_PENDING_TASKS_LIMIT}). Halting to prevent task "
+ f"explosion. Last failed task: {task.id}"
+ )
+ self._cleanup_task_tracking(task.id)
+ # Mark task as completed for dependency tracking before halting
+ self._completed_tasks.append(task)
+ if task.id in self._assignees:
+ await self._channel.archive_task(task.id)
return True
if task.get_depth() > 3:
@@ -1777,8 +1875,6 @@ class Workforce(BaseNode):
# Mark task as completed for dependency tracking
self._completed_tasks.append(task)
- # Post next ready tasks
-
# Sync shared memory after task completion to share knowledge
if self.share_memory:
logger.info(
@@ -1792,7 +1888,7 @@ class Workforce(BaseNode):
async def _handle_completed_task(self, task: Task) -> None:
if self.metrics_logger:
- worker_id = self._assignees.get(task.id, "unknown")
+ worker_id = task.assigned_worker_id or "unknown"
processing_time_seconds = None
token_usage = None
@@ -1801,7 +1897,7 @@ class Workforce(BaseNode):
processing_time_seconds = (
time.time() - self._task_start_times[task.id]
)
- del self._task_start_times[task.id] # Prevent memory leaks
+ self._cleanup_task_tracking(task.id)
elif (
task.additional_info is not None
and 'processing_time_seconds' in task.additional_info
@@ -1995,8 +2091,19 @@ class Workforce(BaseNode):
)
self._last_snapshot_time = time.time()
- # Get returned task (this may block until a task is returned)
+ # Get returned task
returned_task = await self._get_returned_task()
+
+ # If no task was returned, continue
+ if returned_task is None:
+ logger.debug(
+ f"No task returned in workforce {self.node_id}. "
+ f"Pending: {len(self._pending_tasks)}, "
+ f"In-flight: {self._in_flight_tasks}"
+ )
+ await self._post_ready_tasks()
+ continue
+
self._in_flight_tasks -= 1
# Check for stop request after getting task
@@ -2006,22 +2113,72 @@ class Workforce(BaseNode):
# Process the returned task based on its state
if returned_task.state == TaskState.DONE:
- print(
- f"{Fore.CYAN}🎯 Task {returned_task.id} completed "
- f"successfully.{Fore.RESET}"
- )
- await self._handle_completed_task(returned_task)
+ # Check if the "completed" task actually failed to provide
+ # useful results
+ if is_task_result_insufficient(returned_task):
+ result_preview = (
+ returned_task.result[:100] + "..."
+ if returned_task.result
+ else "No result"
+ )
+ logger.warning(
+ f"Task {returned_task.id} marked as DONE but "
+ f"result is insufficient. "
+ f"Treating as failed. Result: '{result_preview}'"
+ )
+ returned_task.state = TaskState.FAILED
+ try:
+ halt = await self._handle_failed_task(
+ returned_task
+ )
+ if not halt:
+ continue
+ print(
+ f"{Fore.RED}Task {returned_task.id} has "
+ f"failed for {MAX_TASK_RETRIES} times after "
+ f"insufficient results, halting the "
+ f"workforce. Final error: "
+ f"{returned_task.result or 'Unknown error'}"
+ f"{Fore.RESET}"
+ )
+ await self._graceful_shutdown(returned_task)
+ break
+ except Exception as e:
+ logger.error(
+ f"Error handling insufficient task result "
+ f"{returned_task.id}: {e}",
+ exc_info=True,
+ )
+ continue
+ else:
+ print(
+ f"{Fore.CYAN}🎯 Task {returned_task.id} completed "
+ f"successfully.{Fore.RESET}"
+ )
+ await self._handle_completed_task(returned_task)
elif returned_task.state == TaskState.FAILED:
- halt = await self._handle_failed_task(returned_task)
- if not halt:
+ try:
+ halt = await self._handle_failed_task(returned_task)
+ if not halt:
+ continue
+ print(
+ f"{Fore.RED}Task {returned_task.id} has failed "
+ f"for {MAX_TASK_RETRIES} times, halting "
+ f"the workforce. Final error: "
+ f"{returned_task.result or 'Unknown error'}"
+ f"{Fore.RESET}"
+ )
+ # Graceful shutdown instead of immediate break
+ await self._graceful_shutdown(returned_task)
+ break
+ except Exception as e:
+ logger.error(
+ f"Error handling failed task "
+ f"{returned_task.id}: {e}",
+ exc_info=True,
+ )
+ # Continue to prevent hanging
continue
- print(
- f"{Fore.RED}Task {returned_task.id} has failed "
- f"for 3 times, halting the workforce.{Fore.RESET}"
- )
- # Graceful shutdown instead of immediate break
- await self._graceful_shutdown(returned_task)
- break
elif returned_task.state == TaskState.OPEN:
# TODO: Add logic for OPEN
pass
@@ -2031,7 +2188,18 @@ class Workforce(BaseNode):
)
except Exception as e:
- logger.error(f"Error processing task: {e}")
+ # Decrement in-flight counter to prevent hanging
+ if self._in_flight_tasks > 0:
+ self._in_flight_tasks -= 1
+
+ logger.error(
+ f"Error processing task in workforce {self.node_id}: {e}"
+ f"Workforce state - Pending tasks: "
+ f"{len(self._pending_tasks)}, "
+ f"In-flight tasks: {self._in_flight_tasks}, "
+ f"Completed tasks: {len(self._completed_tasks)}"
+ )
+
if self._stop_requested:
break
# Continue with next iteration unless stop is requested
@@ -2085,11 +2253,38 @@ class Workforce(BaseNode):
r"""Stop all the child nodes under it. The node itself will be stopped
by its parent node.
"""
+ # Stop all child nodes first
for child in self._children:
if child._running:
child.stop()
- for child_task in self._child_listening_tasks:
- child_task.cancel()
+
+ # Cancel child listening tasks
+ if self._child_listening_tasks:
+ try:
+ loop = asyncio.get_running_loop()
+ if loop and not loop.is_closed():
+ # Create graceful cleanup task
+ async def cleanup():
+ await asyncio.sleep(0.1) # Brief grace period
+ for task in self._child_listening_tasks:
+ if not task.done():
+ task.cancel()
+ await asyncio.gather(
+ *self._child_listening_tasks,
+ return_exceptions=True,
+ )
+
+ self._cleanup_task = loop.create_task(cleanup())
+ else:
+ # No active loop, cancel immediately
+ for task in self._child_listening_tasks:
+ task.cancel()
+ except (RuntimeError, Exception) as e:
+ # Fallback: cancel immediately
+ logger.debug(f"Exception during task cleanup: {e}")
+ for task in self._child_listening_tasks:
+ task.cancel()
+
self._running = False
def clone(self, with_memory: bool = False) -> 'Workforce':
diff --git a/camel/societies/workforce/workforce_logger.py b/camel/societies/workforce/workforce_logger.py
index 8fd4c4112..83e4cd65f 100644
--- a/camel/societies/workforce/workforce_logger.py
+++ b/camel/societies/workforce/workforce_logger.py
@@ -488,7 +488,6 @@ class WorkforceLogger:
'worker_utilization': {},
'current_pending_tasks': 0,
'total_workforce_running_time_seconds': 0.0,
- 'avg_task_queue_time_seconds': 0.0,
}
task_start_times: Dict[str, float] = {}
diff --git a/camel/tasks/task.py b/camel/tasks/task.py
index ee22c6c6a..6b11e249b 100644
--- a/camel/tasks/task.py
+++ b/camel/tasks/task.py
@@ -46,19 +46,35 @@ from .task_prompt import (
logger = get_logger(__name__)
+class TaskValidationMode(Enum):
+ r"""Validation modes for different use cases."""
+
+ INPUT = "input" # For validating task content before processing
+ OUTPUT = "output" # For validating task results after completion
+
+
def validate_task_content(
- content: str, task_id: str = "unknown", min_length: int = 10
+ content: str,
+ task_id: str = "unknown",
+ min_length: int = 5,
+ mode: TaskValidationMode = TaskValidationMode.INPUT,
+ check_failure_patterns: bool = True,
) -> bool:
- r"""Validates task result content to avoid silent failures.
- It performs basic checks to ensure the content meets minimum
- quality standards.
+ r"""Unified validation for task content and results to avoid silent
+ failures. Performs comprehensive checks to ensure content meets quality
+ standards.
Args:
- content (str): The task result content to validate.
+ content (str): The task content or result to validate.
task_id (str): Task ID for logging purposes.
(default: :obj:`"unknown"`)
min_length (int): Minimum content length after stripping whitespace.
- (default: :obj:`10`)
+ (default: :obj:`5`)
+ mode (TaskValidationMode): Validation mode - INPUT for task content,
+ OUTPUT for task results. (default: :obj:`TaskValidationMode.INPUT`)
+ check_failure_patterns (bool): Whether to check for failure indicators
+ in the content. Only effective in OUTPUT mode.
+ (default: :obj:`True`)
Returns:
bool: True if content passes validation, False otherwise.
@@ -85,14 +101,70 @@ def validate_task_content(
)
return False
+ # 4: For OUTPUT mode, check for failure patterns if enabled
+ if mode == TaskValidationMode.OUTPUT and check_failure_patterns:
+ content_lower = stripped_content.lower()
+
+ # Check for explicit failure indicators
+ failure_indicators = [
+ "i cannot complete",
+ "i cannot do",
+ "task failed",
+ "unable to complete",
+ "cannot be completed",
+ "failed to complete",
+ "i cannot",
+ "not possible",
+ "impossible to",
+ "cannot perform",
+ ]
+
+ if any(indicator in content_lower for indicator in failure_indicators):
+ logger.warning(
+ f"Task {task_id}: Failure indicator detected in result. "
+ f"Content preview: '{stripped_content[:100]}...'"
+ )
+ return False
+
+ # Check for responses that are just error messages or refusals
+ if content_lower.startswith(("error", "failed", "cannot", "unable")):
+ logger.warning(
+ f"Task {task_id}: Error/refusal pattern detected at start. "
+ f"Content preview: '{stripped_content[:100]}...'"
+ )
+ return False
+
# All validation checks passed
logger.debug(
- f"Task {task_id}: Content validation passed "
+ f"Task {task_id}: {mode.value} validation passed "
f"({len(stripped_content)} chars)"
)
return True
+def is_task_result_insufficient(task: "Task") -> bool:
+ r"""Check if a task result is insufficient and should be treated as failed.
+
+ This is a convenience wrapper around validate_task_content for backward
+ compatibility and semantic clarity when checking task results.
+
+ Args:
+ task (Task): The task to check.
+
+ Returns:
+ bool: True if the result is insufficient, False otherwise.
+ """
+ if not hasattr(task, 'result') or task.result is None:
+ return True
+
+ return not validate_task_content(
+ content=task.result,
+ task_id=task.id,
+ mode=TaskValidationMode.OUTPUT,
+ check_failure_patterns=True,
+ )
+
+
def parse_response(
response: str, task_id: Optional[str] = None
) -> List["Task"]:
@@ -157,6 +229,8 @@ class Task(BaseModel):
(default: :obj:`""`)
failure_count (int): The failure count for the task.
(default: :obj:`0`)
+ assigned_worker_id (Optional[str]): The ID of the worker assigned to
+ this task. (default: :obj:`None`)
additional_info (Optional[Dict[str, Any]]): Additional information for
the task. (default: :obj:`None`)
image_list (Optional[List[Image.Image]]): Optional list of PIL Image
@@ -187,6 +261,8 @@ class Task(BaseModel):
failure_count: int = 0
+ assigned_worker_id: Optional[str] = None
+
additional_info: Optional[Dict[str, Any]] = None
image_list: Optional[List[Image.Image]] = None
diff --git a/camel/toolkits/human_toolkit.py b/camel/toolkits/human_toolkit.py
index 8c12d9968..ed3b9b32f 100644
--- a/camel/toolkits/human_toolkit.py
+++ b/camel/toolkits/human_toolkit.py
@@ -25,13 +25,21 @@ class HumanToolkit(BaseToolkit):
r"""A class representing a toolkit for human interaction."""
def ask_human_via_console(self, question: str) -> str:
- r"""Ask a question to the human via the console.
+ r"""Use this tool to ask a question to the user when you are stuck,
+ need clarification, or require a decision to be made. This is a
+ two-way communication channel that will wait for the user's response.
+ You should use it to:
+ - Clarify ambiguous instructions or requirements.
+ - Request missing information that you cannot find (e.g., login
+ credentials, file paths).
+ - Ask for a decision when there are multiple viable options.
+ - Seek help when you encounter an error you cannot resolve on your own.
Args:
- question (str): The question to ask the human.
+ question (str): The question to ask the user.
Returns:
- str: The answer from the human.
+ str: The user's response to the question.
"""
print(f"Question: {question}")
logger.info(f"Question: {question}")
@@ -40,11 +48,18 @@ class HumanToolkit(BaseToolkit):
return reply
def send_message_to_user(self, message: str) -> None:
- r"""Send a message to the user, without waiting for
- a response. This will send to stdout in a noticeable way.
-
- This is guaranteed to reach the user regardless of
- actual user interface.
+ r"""Use this tool to send a message to the user to keep them
+ informed about your progress, decisions, or actions.
+ This is a one-way communication channel from you to the user and does
+ not require a response. You should use it to:
+ - Announce what you are about to do
+ (e.g., "I will now search for papers on GUI Agents.")
+ - Report the result of an action
+ (e.g., "I have found 15 relevant papers.")
+ - State a decision
+ (e.g., "I will now analyze the top 10 papers.")
+ - Inform the user about your current state if you are performing a
+ task.
Args:
message (str): The message to send to the user.
diff --git a/camel/toolkits/non_visual_browser_toolkit/browser_non_visual_toolkit.py b/camel/toolkits/non_visual_browser_toolkit/browser_non_visual_toolkit.py
index 58454ef54..167ed818b 100644
--- a/camel/toolkits/non_visual_browser_toolkit/browser_non_visual_toolkit.py
+++ b/camel/toolkits/non_visual_browser_toolkit/browser_non_visual_toolkit.py
@@ -176,7 +176,7 @@ class BrowserNonVisualToolkit(BaseToolkit):
self._agent = None
# Close session
- await self._session.close()
+ await NVBrowserSession.close_all_sessions()
return "Browser session closed."
async def visit_page(self, url: str) -> Dict[str, str]:
diff --git a/camel/toolkits/non_visual_browser_toolkit/nv_browser_session.py b/camel/toolkits/non_visual_browser_toolkit/nv_browser_session.py
index 7310721ba..2b4e6c14c 100644
--- a/camel/toolkits/non_visual_browser_toolkit/nv_browser_session.py
+++ b/camel/toolkits/non_visual_browser_toolkit/nv_browser_session.py
@@ -13,8 +13,11 @@
# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
from __future__ import annotations
+import asyncio
from pathlib import Path
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any, ClassVar, Dict, Optional
+
+from camel.logger import get_logger
from .actions import ActionExecutor
from .snapshot import PageSnapshot
@@ -28,6 +31,9 @@ if TYPE_CHECKING:
)
+logger = get_logger(__name__)
+
+
class NVBrowserSession:
"""Lightweight wrapper around Playwright for non-visual (headless)
browsing.
@@ -35,15 +41,37 @@ class NVBrowserSession:
It provides a single *Page* instance plus helper utilities (snapshot &
executor). Multiple toolkits or agents can reuse this class without
duplicating Playwright setup code.
+
+ This class is a singleton per event-loop.
"""
# Configuration constants
DEFAULT_NAVIGATION_TIMEOUT = 10000 # 10 seconds
NETWORK_IDLE_TIMEOUT = 5000 # 5 seconds
+ _sessions: ClassVar[
+ Dict[asyncio.AbstractEventLoop, "NVBrowserSession"]
+ ] = {}
+
+ _initialized: bool
+
+ def __new__(
+ cls, *, headless: bool = True, user_data_dir: Optional[str] = None
+ ):
+ loop = asyncio.get_running_loop()
+ if loop not in cls._sessions:
+ instance = super().__new__(cls)
+ instance._initialized = False
+ cls._sessions[loop] = instance
+ return cls._sessions[loop]
+
def __init__(
self, *, headless: bool = True, user_data_dir: Optional[str] = None
):
+ if self._initialized:
+ return
+ self._initialized = True
+
self._headless = headless
self._user_data_dir = user_data_dir
@@ -56,8 +84,6 @@ class NVBrowserSession:
self.executor: Optional[ActionExecutor] = None
# Protect browser initialisation against concurrent calls
- import asyncio
-
self._ensure_lock: "asyncio.Lock" = asyncio.Lock()
# ------------------------------------------------------------------
@@ -93,10 +119,6 @@ class NVBrowserSession:
self._browser = await pl.chromium.launch(headless=self._headless)
self._context = await self._browser.new_context()
- from camel.logger import get_logger
-
- _dbg_logger = get_logger(__name__)
-
# Reuse an already open page (persistent context may restore last
# session)
if self._context.pages:
@@ -105,7 +127,7 @@ class NVBrowserSession:
self._page = await self._context.new_page()
# Debug information to help trace concurrency issues
- _dbg_logger.debug(
+ logger.debug(
"Session %s created browser=%s context=%s page=%s (url=%s)",
hex(id(self)),
hex(id(self._browser)) if self._browser else None,
@@ -122,6 +144,11 @@ class NVBrowserSession:
r"""Close all browser resources, ensuring cleanup even if some
operations fail.
"""
+ # The close method will now only close the *current* event-loop's
+ # browser instance. Use `close_all_sessions` for a full cleanup.
+ await self._close_session()
+
+ async def _close_session(self) -> None:
errors: list[str] = []
# Close context first (which closes pages)
@@ -151,13 +178,28 @@ class NVBrowserSession:
# Log errors if any occurred during cleanup
if errors:
- from camel.logger import get_logger
-
- logger = get_logger(__name__)
logger.warning(
"Errors during browser session cleanup: %s", "; ".join(errors)
)
+ @classmethod
+ async def close_all_sessions(cls) -> None:
+ r"""Iterate over all stored sessions and close them."""
+ for loop, session in cls._sessions.items():
+ if loop.is_running():
+ await session._close_session()
+ else:
+ try:
+ if not loop.is_closed():
+ loop.run_until_complete(session._close_session())
+ except Exception as e:
+ logger.warning(
+ "Failed to close session for loop %s: %s",
+ hex(id(loop)),
+ e,
+ )
+ cls._sessions.clear()
+
# ------------------------------------------------------------------
# Convenience wrappers around common actions
# ------------------------------------------------------------------
diff --git a/camel/toolkits/terminal_toolkit.py b/camel/toolkits/terminal_toolkit.py
index 54fbdffc8..d8d9254e9 100644
--- a/camel/toolkits/terminal_toolkit.py
+++ b/camel/toolkits/terminal_toolkit.py
@@ -81,7 +81,7 @@ class TerminalToolkit(BaseToolkit):
self.terminal_ready = threading.Event()
self.gui_thread = None
self.safe_mode = safe_mode
-
+ self._file_initialized = False
self.cloned_env_path = None
self.use_shell_mode = use_shell_mode
@@ -129,25 +129,20 @@ class TerminalToolkit(BaseToolkit):
self.log_file = os.path.join(os.getcwd(), "camel_terminal.txt")
- if os.path.exists(self.log_file):
- with open(self.log_file, "w") as f:
- f.truncate(0)
- f.write("CAMEL Terminal Session\n")
- f.write("=" * 50 + "\n")
- f.write(f"Working Directory: {os.getcwd()}\n")
- f.write("=" * 50 + "\n\n")
- else:
- with open(self.log_file, "w") as f:
- f.write("CAMEL Terminal Session\n")
- f.write("=" * 50 + "\n")
- f.write(f"Working Directory: {os.getcwd()}\n")
- f.write("=" * 50 + "\n\n")
-
# Inform the user
- logger.info(f"Terminal output redirected to: {self.log_file}")
+ logger.info(f"Terminal output will be redirected to: {self.log_file}")
def file_update(output: str):
try:
+ # Initialize file on first write
+ if not self._file_initialized:
+ with open(self.log_file, "w") as f:
+ f.write("CAMEL Terminal Session\n")
+ f.write("=" * 50 + "\n")
+ f.write(f"Working Directory: {os.getcwd()}\n")
+ f.write("=" * 50 + "\n\n")
+ self._file_initialized = True
+
# Directly append to the end of the file
with open(self.log_file, "a") as f:
f.write(output)
@@ -165,6 +160,12 @@ class TerminalToolkit(BaseToolkit):
def _clone_current_environment(self):
r"""Create a new Python virtual environment."""
try:
+ if self.cloned_env_path is None:
+ self._update_terminal_output(
+ "Error: No environment path specified\n"
+ )
+ return
+
if os.path.exists(self.cloned_env_path):
self._update_terminal_output(
f"Using existing environment: {self.cloned_env_path}\n"
diff --git a/camel/toolkits/video_download_toolkit.py b/camel/toolkits/video_download_toolkit.py
index 64a0f1ed5..59754d047 100644
--- a/camel/toolkits/video_download_toolkit.py
+++ b/camel/toolkits/video_download_toolkit.py
@@ -123,6 +123,9 @@ class VideoDownloaderToolkit(BaseToolkit):
yt-dlp will detect if the video is downloaded automatically so there
is no need to check if the video exists.
+ Args:
+ url (str): The URL of the video to download.
+
Returns:
str: The path to the downloaded video file.
"""
@@ -175,7 +178,8 @@ class VideoDownloaderToolkit(BaseToolkit):
dividing the video into equal parts if an integer is provided.
Args:
- video_url (str): The URL of the video to take screenshots.
+ video_path (str): The local path or URL of the video to take
+ screenshots.
amount (int): the amount of evenly split screenshots to capture.
Returns:
diff --git a/docs/conf.py b/docs/conf.py
index 376975792..120e12583 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -27,7 +27,7 @@ sys.path.insert(0, os.path.abspath('..'))
project = 'CAMEL'
copyright = '2024, CAMEL-AI.org'
author = 'CAMEL-AI.org'
-release = '0.2.70'
+release = '0.2.71a1'
html_favicon = (
'https://raw.githubusercontent.com/camel-ai/camel/master/misc/favicon.png'
diff --git a/examples/workforce/eigent.py b/examples/workforce/eigent.py
index cb6e77726..0d72949e9 100644
--- a/examples/workforce/eigent.py
+++ b/examples/workforce/eigent.py
@@ -55,14 +55,18 @@ def developer_agent_factory(
):
r"""Factory for creating a developer agent."""
tools = [
- HumanToolkit().ask_human_via_console,
+ *HumanToolkit().get_tools(),
*TerminalToolkit(clone_current_env=True).get_tools(),
*CodeExecutionToolkit().get_tools(),
*edgeone_pages_mcp_toolkit.get_tools(),
]
system_message = """You are a skilled coding assistant with DIRECT CODE
- EXECUTION CAPABILITIES. You can:
+ EXECUTION CAPABILITIES. You MUST use the `send_message_to_user` tool to
+ inform the user of every decision and action you take. This is a mandatory
+ part of your workflow.
+
+ Your capabilities include:
- WRITE AND EXECUTE code in real-time to solve tasks
- RUN terminal commands to install packages, process files, or test
functionality
@@ -79,7 +83,8 @@ def developer_agent_factory(
- If there's dependency issues when you try to execute code, you should
use the terminal toolkit to install the dependencies.
- ASK for human input via the console if you are stuck or need
- clarification."""
+ clarification.
+ """
return ChatAgent(
system_message=BaseMessage.make_assistant_message(
@@ -97,7 +102,8 @@ def search_agent_factory(
task_id: str,
):
r"""Factory for creating a search agent, based on user-provided code
- structure."""
+ structure.
+ """
tools = [
# FunctionTool(SearchToolkit().search_wiki),
FunctionTool(SearchToolkit().search_exa),
@@ -105,14 +111,20 @@ def search_agent_factory(
# FunctionTool(SearchToolkit().search_baidu),
*BrowserNonVisualToolkit(headless=False).get_tools(),
*TerminalToolkit().get_tools(),
- HumanToolkit().ask_human_via_console,
+ *HumanToolkit().get_tools(),
*Crawl4AIToolkit().get_tools(),
]
system_message = """You are a helpful assistant that can search the web,
extract webpage content, simulate browser actions, and provide relevant
information to solve the given task.
+
+ You MUST use the `send_message_to_user` tool to inform the user of every
+ decision and action you take. This is a mandatory part of your workflow.
+
Keep in mind that:
+ - For each decision you make and action you take, you must send a message
+ to the user to keep them informed.
- Do not be overly confident in your own knowledge. Searching can provide
a broader perspective and help validate existing knowledge.
- If one way fails to provide an answer, try other ways or methods. The
@@ -157,8 +169,7 @@ Here are some tips that help you perform web search:
terms step-by-step to find more urls.
- The results you return do not have to directly answer the original question,
you only need to collect relevant information.
-
- """
+"""
return ChatAgent(
system_message=BaseMessage.make_assistant_message(
@@ -182,14 +193,17 @@ def document_agent_factory(
*PPTXToolkit().get_tools(),
# *google_drive_mcp_toolkit.get_tools(),
# *RetrievalToolkit().get_tools(),
- HumanToolkit().ask_human_via_console,
+ *HumanToolkit().get_tools(),
*MarkItDownToolkit().get_tools(),
*ExcelToolkit().get_tools(),
]
system_message = """You are a Document Processing Assistant specialized in
- creating, modifying, and managing various document formats. Your
- capabilities include:
+ creating, modifying, and managing various document formats. You MUST use
+ the `send_message_to_user` tool to inform the user of every decision and
+ action you take. This is a mandatory part of your workflow.
+
+ Your capabilities include:
1. Document Creation & Editing:
- Create and write to various file formats including Markdown (.md),
@@ -258,12 +272,15 @@ def multi_modal_agent_factory(model: BaseModelBackend, task_id: str):
*AudioAnalysisToolkit().get_tools(),
*ImageAnalysisToolkit().get_tools(),
*DalleToolkit().get_tools(),
- HumanToolkit().ask_human_via_console,
+ *HumanToolkit().get_tools(),
]
system_message = """You are a Multi-Modal Processing Assistant specialized
- in analyzing and generating various types of media content. Your
- capabilities include:
+ in analyzing and generating various types of media content. You MUST use
+ the `send_message_to_user` tool to inform the user of every decision and
+ action you take. This is a mandatory part of your workflow.
+
+ Your capabilities include:
1. Video & Audio Analysis:
- Download videos from URLs for analysis.
@@ -312,9 +329,13 @@ def social_medium_agent_factory(model: BaseModelBackend, task_id: str):
return ChatAgent(
BaseMessage.make_assistant_message(
role_name="Social Medium Agent",
- content="""You are a Social Media Management Assistant with
- comprehensive capabilities across multiple platforms. Your
- integrated toolkits enable you to:
+ content="""
+You are a Social Media Management Assistant with comprehensive capabilities
+across multiple platforms. You MUST use the `send_message_to_user` tool to
+inform the user of every decision and action you take. This is a mandatory
+part of your workflow.
+
+Your integrated toolkits enable you to:
1. WhatsApp Business Management (WhatsAppToolkit):
- Send text and template messages to customers via the WhatsApp Business
@@ -365,7 +386,7 @@ operations.
*RedditToolkit().get_tools(),
*NotionToolkit().get_tools(),
*SlackToolkit().get_tools(),
- HumanToolkit().ask_human_via_console,
+ *HumanToolkit().get_tools(),
],
)
@@ -400,13 +421,34 @@ async def main():
# Create custom agents for the workforce
coordinator_agent = ChatAgent(
- "You are a helpful coordinator.", model=model_backend_reason
+ "You are a helpful coordinator. You MUST use the "
+ "`send_message_to_user` tool to inform the user of every "
+ "decision and action you take. This is a mandatory part of your "
+ "workflow.",
+ model=model_backend_reason,
+ tools=[
+ *HumanToolkit().get_tools(),
+ ],
)
task_agent = ChatAgent(
- "You are a helpful task planner.", model=model_backend_reason
+ "You are a helpful task planner. You MUST use the "
+ "`send_message_to_user` tool to inform the user of every "
+ "decision and action you take. This is a mandatory part of your "
+ "workflow.",
+ model=model_backend_reason,
+ tools=[
+ *HumanToolkit().get_tools(),
+ ],
)
new_worker_agent = ChatAgent(
- "You are a helpful worker.", model=model_backend
+ "You are a helpful worker. You MUST use the "
+ "`send_message_to_user` tool to inform the user of every "
+ "decision and action you take. This is a mandatory part of your "
+ "workflow.",
+ model=model_backend,
+ tools=[
+ *HumanToolkit().get_tools(),
+ ],
)
# Create agents using factory functions
diff --git a/pyproject.toml b/pyproject.toml
index 27d8b20b1..3a5d97fb2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "camel-ai"
-version = "0.2.70"
+version = "0.2.71a1"
description = "Communicative Agents for AI Society Study"
authors = [{ name = "CAMEL-AI.org" }]
requires-python = ">=3.10,<3.13"
diff --git a/uv.lock b/uv.lock
index b49d9282d..8dfb1c979 100644
--- a/uv.lock
+++ b/uv.lock
@@ -632,7 +632,7 @@ wheels = [
[[package]]
name = "camel-ai"
-version = "0.2.70"
+version = "0.2.71a1"
source = { editable = "." }
dependencies = [
{ name = "colorama" },
@@ -8276,7 +8276,7 @@ wheels = [
[[package]]
name = "weaviate-client"
-version = "4.15.3"
+version = "4.15.4"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "authlib" },
@@ -8288,9 +8288,9 @@ dependencies = [
{ name = "pydantic" },
{ name = "validators" },
]
-sdist = { url = "https://files.pythonhosted.org/packages/96/a3/1c69fd6c7ce176583acd784d35f57e8015c95880a70813f56babe38b00c9/weaviate_client-4.15.3.tar.gz", hash = "sha256:faeff93a4d8baac0a88d9eb42a419689b8f9f79f446e00aa5a7e6f76065ec3fe", size = 663964, upload-time = "2025-06-23T12:53:27.509Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/ba/90/1510c0b76abee95a70a828451da0c04445a4bcbabae74bf96f522b0a599d/weaviate_client-4.15.4.tar.gz", hash = "sha256:005e7a6cee52ff4ac66f244a572b5ed98dd0e15bfda380979a88fddf692720df", size = 663413, upload-time = "2025-06-26T07:01:45.545Z" }
wheels = [
- { url = "https://files.pythonhosted.org/packages/8f/8e/4c7060dd9a45036d81ef1102217531b5e727f1cc6576fa5dac9ff9b0b971/weaviate_client-4.15.3-py3-none-any.whl", hash = "sha256:28839ce4117f78fc8a48188c33ce694f83b98ad1f71c4c321aaaef202ac79b6b", size = 433729, upload-time = "2025-06-23T12:53:25.802Z" },
+ { url = "https://files.pythonhosted.org/packages/cc/41/f2662a2860493acc345537a1f8e8dbb3695e485179114e295ffd0ec4909c/weaviate_client-4.15.4-py3-none-any.whl", hash = "sha256:870b73495b8e5849003690f7c36f2795b90765e62482f07ab71275dbd21b271d", size = 432978, upload-time = "2025-06-26T07:01:43.955Z" },
]
[[package]]