feat: add reasoning decorator to browser toolkit

YunfeiZHAO · YunfeiZHAO · commit ad53d205d4fd · 2025-12-09T02:48:16.000+01:00
diff --git a/camel/toolkits/_utils.py b/camel/toolkits/_utils.py
@@ -0,0 +1,134 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# =========
+import functools
+import inspect
+
+from camel.logger import get_logger
+logger = get_logger(__name__)
+
+
+def add_reason_field(func):
+    """
+    Decorator to enable reasoning for tool functions.
+    1.It modifies the function's signature to add a 'reason' parameter.
+    2.The 'reason' argument is a string describing why the tool is being called and it is
+      added to the function docstring.
+    3.It wraps the original function to ensure its return value includes a 'reason' key.
+
+    Note: This decorator can only be applied to functions with a return type of Dict.
+
+    """
+    sig = inspect.signature(func)
+    # Check return annotation
+    if sig.return_annotation is inspect.Signature.empty or (
+        getattr(sig.return_annotation, '__origin__', None) is not dict and
+        sig.return_annotation is not dict
+    ):
+        logger.info(
+            f"add_reason_field: Function '{func.__name__}' does not have return type Dict. "
+            "Reasoning will not be applied."
+        )
+        return func
+
+    # Patch signature
+    params = list(sig.parameters.values())
+    # Only add reason if not already present
+    if "reason" not in sig.parameters:
+        params.append(
+            inspect.Parameter(
+                "reason",
+                inspect.Parameter.KEYWORD_ONLY,
+                default="",
+                annotation=str,
+            )
+        )
+    new_sig = sig.replace(parameters=params)
+
+    # Patch docstring
+    doc = func.__doc__ or ""
+    lines = doc.splitlines()
+    
+    # Add reason to Args section
+    if "Args:" in doc:
+        for i, line in enumerate(lines):
+            if "Args:" in line:
+                indent = line[:line.index("Args:")]
+                reason_doc = f"{indent}    reason (str): The reason why this tool is called."
+                lines.insert(i + 1, reason_doc)
+                break
+    else:
+        lines.extend(["", "Args:", "    reason (str): The reason why this tool is called."])
+
+    # Add reason to Returns section
+    returns_idx = None
+    for i, line in enumerate(lines):
+        if "Returns:" in line:
+            returns_idx = i
+            indent = line[:line.index("Returns:")]
+            break
+
+    if returns_idx is not None:
+        # Find where Returns section ends by checking indentation
+        end_idx = len(lines)
+        for j in range(returns_idx + 1, len(lines)):
+            line = lines[j]
+            # Empty line or line with same/less indentation as "Returns:" = end of section
+            if line.strip() == "":
+                continue
+            if not line.startswith(indent + " "):
+                end_idx = j
+                break
+        
+        # Remove existing reason lines
+        filtered = []
+        for i, line in enumerate(lines):
+            if '"reason"' not in line and "'reason'" not in line:
+                filtered.append(line)
+            elif i < returns_idx or i >= end_idx:
+                filtered.append(line)
+        
+        lines = filtered
+        
+        # Recalculate end_idx after filtering
+        end_idx = len(lines)
+        for j in range(returns_idx + 1, len(lines)):
+            line = lines[j]
+            if line.strip() == "":
+                continue
+            if not line.startswith(indent + " "):
+                end_idx = j
+                break
+        
+        # Remove trailing empty lines in Returns section before inserting reason
+        while end_idx > returns_idx + 1 and lines[end_idx - 1].strip() == "":
+            end_idx -= 1
+        
+        # Append reason line at end of Returns section
+        reason_line = f'{indent}        - "reason" (str): tool call reason.'
+        lines.insert(end_idx, reason_line)
+    elif "Returns:" not in doc:
+        lines.extend(["", "Returns:", "  dict: The result dictionary.", '        - "reason" (str): tool call reason.'])
+
+    doc = "\n".join(lines)
+
+    @functools.wraps(func)
+    async def wrapper(*args, reason: str = "", **kwargs):
+        result = await func(*args, **kwargs)
+        # No need to check type here, as enforced by decorator
+        result["reason"] = reason
+        return result
+    wrapper.__signature__ = new_sig
+    wrapper.__doc__ = doc
+    return wrapper
diff --git a/camel/toolkits/hybrid_browser_toolkit/config_loader.py b/camel/toolkits/hybrid_browser_toolkit/config_loader.py
@@ -58,6 +58,7 @@ class ToolkitConfig:
     log_dir: Optional[str] = None
     session_id: Optional[str] = None
     enabled_tools: Optional[list] = None
+    enable_reasoning: bool = False
 
 
 class ConfigLoader:
@@ -123,6 +124,8 @@ def from_kwargs(cls, **kwargs) -> 'ConfigLoader':
                 toolkit_kwargs["session_id"] = value
             elif key == "enabledTools":
                 toolkit_kwargs["enabled_tools"] = value
+            elif key == "enableReasoning":
+                toolkit_kwargs["enable_reasoning"] = value
             elif key == "fullVisualMode":
                 browser_kwargs["full_visual_mode"] = value
 
diff --git a/camel/toolkits/hybrid_browser_toolkit/hybrid_browser_toolkit.py b/camel/toolkits/hybrid_browser_toolkit/hybrid_browser_toolkit.py
@@ -39,6 +39,9 @@ class HybridBrowserToolkit(BaseToolkit):
         cache_dir (str): Directory for caching. Defaults to "tmp/".
         enabled_tools (Optional[List[str]]): List of enabled tools.
             Defaults to None.
+        enable_reasoning (bool): Whether to enable reasoning when agent
+            is using the browser toolkit. Defaults to False. agent will
+            provide explanations for its actions when this is enabled.
         browser_log_to_file (bool): Whether to log browser actions to
             file. Defaults to False.
         log_dir (Optional[str]): Custom directory path for log files.
@@ -93,6 +96,7 @@ def __new__(
         stealth: bool = False,
         cache_dir: Optional[str] = None,
         enabled_tools: Optional[List[str]] = None,
+        enable_reasoning: bool = False,
         browser_log_to_file: bool = False,
         log_dir: Optional[str] = None,
         session_id: Optional[str] = None,
@@ -127,6 +131,9 @@ def __new__(
             cache_dir (str): Directory for caching. Defaults to "tmp/".
             enabled_tools (Optional[List[str]]): List of enabled tools.
                 Defaults to None.
+            enable_reasoning (bool): Whether to enable reasoning when agent
+                is using the browser toolkit. Defaults to False. agent will
+                provide explanations for its actions when this is enabled.
             browser_log_to_file (bool): Whether to log browser actions to
                 file. Defaults to False.
             log_dir (Optional[str]): Custom directory path for log files.
@@ -182,6 +189,7 @@ def __new__(
                 stealth=stealth,
                 cache_dir=cache_dir,
                 enabled_tools=enabled_tools,
+                enable_reasoning=enable_reasoning,
                 browser_log_to_file=browser_log_to_file,
                 log_dir=log_dir,
                 session_id=session_id,
diff --git a/camel/toolkits/hybrid_browser_toolkit/hybrid_browser_toolkit_ts.py b/camel/toolkits/hybrid_browser_toolkit/hybrid_browser_toolkit_ts.py
@@ -32,6 +32,8 @@
 from camel.toolkits.function_tool import FunctionTool
 from camel.utils.commons import dependencies_required
 
+from camel.toolkits._utils import add_reason_field
+
 from .config_loader import ConfigLoader
 from .ws_wrapper import WebSocketBrowserWrapper, high_level_action
 
@@ -99,6 +101,7 @@ def __init__(
         stealth: bool = False,
         cache_dir: Optional[str] = None,
         enabled_tools: Optional[List[str]] = None,
+        enable_reasoning: bool = False,
         browser_log_to_file: bool = False,
         log_dir: Optional[str] = None,
         session_id: Optional[str] = None,
@@ -128,6 +131,9 @@ def __init__(
             cache_dir (str): Directory for caching. Defaults to "tmp/".
             enabled_tools (Optional[List[str]]): List of enabled tools.
             Defaults to None.
+            enable_reasoning (bool): Whether to enable reasoning when agent
+                is using the browser toolkit. Defaults to False. agent will
+                provide explanations for its actions when this is enabled.
             browser_log_to_file (bool): Whether to log browser actions to
             file. Defaults to False.
             log_dir (Optional[str]): Custom directory path for log files.
@@ -187,6 +193,7 @@ def __init__(
             log_dir=log_dir,
             session_id=session_id,
             enabled_tools=enabled_tools,
+            enable_reasoning=enable_reasoning,
             connect_over_cdp=connect_over_cdp,
             cdp_url=cdp_url,
             cdp_keep_current_page=cdp_keep_current_page,
@@ -206,17 +213,22 @@ def __init__(
                 "is True, the browser will keep the current page and not "
                 "navigate to any URL."
             )
+        # toolkit settings
+        self._cache_dir = toolkit_config.cache_dir
+        self._browser_log_to_file = toolkit_config.browser_log_to_file
+        self._enabled_tools = toolkit_config.enabled_tools
+        self._enable_reasoning = toolkit_config.enable_reasoning
 
+        # browser settings
         self._headless = browser_config.headless
         self._user_data_dir = browser_config.user_data_dir
         self._stealth = browser_config.stealth
-        self._cache_dir = toolkit_config.cache_dir
-        self._browser_log_to_file = toolkit_config.browser_log_to_file
         self._default_start_url = browser_config.default_start_url
         self._session_id = toolkit_config.session_id or "default"
         self._viewport_limit = browser_config.viewport_limit
         self._full_visual_mode = browser_config.full_visual_mode
 
+        # timeout settings
         self._default_timeout = browser_config.default_timeout
         self._short_timeout = browser_config.short_timeout
         self._navigation_timeout = browser_config.navigation_timeout
@@ -227,24 +239,30 @@ def __init__(
             browser_config.dom_content_loaded_timeout
         )
 
-        if enabled_tools is None:
-            self.enabled_tools = self.DEFAULT_TOOLS.copy()
+        if self._enabled_tools is None:
+            self._enabled_tools = self.DEFAULT_TOOLS.copy()
         else:
             invalid_tools = [
-                tool for tool in enabled_tools if tool not in self.ALL_TOOLS
+                tool for tool in self._enabled_tools if tool not in self.ALL_TOOLS
             ]
             if invalid_tools:
                 raise ValueError(
                     f"Invalid tools specified: {invalid_tools}. "
                     f"Available tools: {self.ALL_TOOLS}"
                 )
-            self.enabled_tools = enabled_tools.copy()
 
-        logger.info(f"Enabled tools: {self.enabled_tools}")
+        logger.info(f"Enabled tools: {self._enabled_tools}")
 
         self._ws_wrapper: Optional[WebSocketBrowserWrapper] = None
         self._ws_config = self.config_loader.to_ws_config()
 
+        # Dynamically wrap tool methods if reasoning is enabled
+        if self._enable_reasoning:
+            for tool_name in self._enabled_tools:
+                method = getattr(self, tool_name, None)
+                if method and callable(method):
+                    setattr(self, tool_name, add_reason_field(method))
+
     async def _ensure_ws_wrapper(self):
         """Ensure WebSocket wrapper is initialized."""
         if self._ws_wrapper is None:
@@ -1913,7 +1931,7 @@ def clone_for_new_session(
             stealth=self._stealth,
             cache_dir=f"{self._cache_dir.rstrip('/')}_clone_"
             f"{new_session_id}/",
-            enabled_tools=self.enabled_tools.copy(),
+            enabled_tools=self._enabled_tools.copy(),
             browser_log_to_file=self._browser_log_to_file,
             session_id=new_session_id,
             default_start_url=self._default_start_url,
@@ -1958,16 +1976,15 @@ def get_tools(self) -> List[FunctionTool]:
             "browser_sheet_read": self.browser_sheet_read,
         }
 
-        enabled_tools = []
-
-        for tool_name in self.enabled_tools:
+        tools = []
+        for tool_name in self._enabled_tools:
             if tool_name in tool_map:
                 tool = FunctionTool(
                     cast(Callable[..., Any], tool_map[tool_name])
                 )
-                enabled_tools.append(tool)
+                tools.append(tool)
             else:
                 logger.warning(f"Unknown tool name: {tool_name}")
 
-        logger.info(f"Returning {len(enabled_tools)} enabled tools")
-        return enabled_tools
+        logger.info(f"Returning {len(tools)} enabled tools")
+        return tools
diff --git a/examples/toolkits/browser_toolkit_with_reasoning.ipynb b/examples/toolkits/browser_toolkit_with_reasoning.ipynb
diff --git a/examples/workforce/eigent.py b/examples/workforce/eigent.py
