enhance: improve OutlookMailToolkit with run_async and explicit redirect… PR#3419 (#3492)

Co-authored-by: Tanuj Taneja <[email protected]>

Author: waleedalzarooni

camel/toolkits/microsoft_outlook_mail_toolkit.py

@@ -27,6 +27,7 @@
 from camel.toolkits import FunctionTool
 from camel.toolkits.base import BaseToolkit
 from camel.utils import MCPServer, api_keys_required
+from camel.utils.commons import run_async
 
 load_dotenv()
 logger = get_logger(__name__)
@@ -73,8 +74,8 @@ class CustomAzureCredential:
         tenant_id (str): The Microsoft tenant ID.
         refresh_token (str): The refresh token from OAuth flow.
         scopes (List[str]): List of OAuth permission scopes.
-        token_file_path (Optional[Path]): Path to persist the refresh token.
-            If None, token persistence is disabled.
+        refresh_token_file_path (Optional[Path]): File path of json file
+        with refresh token.
     """
 
     def __init__(
@@ -84,14 +85,14 @@ def __init__(
         tenant_id: str,
         refresh_token: str,
         scopes: List[str],
-        token_file_path: Optional[Path],
+        refresh_token_file_path: Optional[Path],
     ):
         self.client_id = client_id
         self.client_secret = client_secret
         self.tenant_id = tenant_id
         self.refresh_token = refresh_token
         self.scopes = scopes
-        self.token_file_path = token_file_path
+        self.refresh_token_file_path = refresh_token_file_path
 
         self._access_token = None
         self._expires_at = 0
@@ -144,18 +145,20 @@ def _save_refresh_token(self, refresh_token: str):
         Args:
             refresh_token (str): The refresh token to save.
         """
-        if not self.token_file_path:
+        if not self.refresh_token_file_path:
             logger.info("Token file path not set, skipping token save")
             return
 
         token_data = {"refresh_token": refresh_token}
 
         try:
             # Create parent directories if they don't exist
-            self.token_file_path.parent.mkdir(parents=True, exist_ok=True)
+            self.refresh_token_file_path.parent.mkdir(
+                parents=True, exist_ok=True
+            )
 
             # Write new refresh token to file
-            with open(self.token_file_path, 'w') as f:
+            with open(self.refresh_token_file_path, 'w') as f:
                 json.dump(token_data, f, indent=2)
         except Exception as e:
             logger.warning(f"Failed to save refresh token: {e!s}")
@@ -191,35 +194,38 @@ def get_token(self, *args, **kwargs):
 
 @MCPServer()
 class OutlookMailToolkit(BaseToolkit):
-    """A class representing a toolkit for Microsoft Outlook operations.
+    """A comprehensive toolkit for Microsoft Outlook Mail operations.
 
-    This class provides methods for interacting with Microsoft Outlook via
-    the Microsoft Graph API.
+    This class provides methods for Outlook Mail operations including sending
+    emails, managing drafts, replying to mails, deleting mails, fetching
+    mails and attachments and changing folder of mails.
+    API keys can be accessed in the Azure portal (https://portal.azure.com/)
     """
 
     def __init__(
         self,
         timeout: Optional[float] = None,
-        token_file_path: Optional[str] = None,
+        refresh_token_file_path: Optional[str] = None,
     ):
         """Initializes a new instance of the OutlookMailToolkit.
 
         Args:
             timeout (Optional[float]): The timeout value for API requests
                 in seconds. If None, no timeout is applied.
                 (default: :obj:`None`)
-            token_file_path (Optional[str]): The path to the file where the
-                refresh token will be stored. If None, token persistence is
-                disabled and browser authentication will be required on each
-                initialization. If provided, the token will be saved to and
-                loaded from this path. (default: :obj:`None`)
+            refresh_token_file_path (Optional[str]): The path of json file
+                where refresh token is stored. If None, authentication using
+                web browser will be required on each initialization. If
+                provided, the refresh token is read from the file, used, and
+                automatically updated when it nears expiry.
+                (default: :obj:`None`)
         """
         super().__init__(timeout=timeout)
 
         self.scopes = ["Mail.Send", "Mail.ReadWrite"]
         self.redirect_uri = self._get_dynamic_redirect_uri()
-        self.token_file_path = (
-            Path(token_file_path) if token_file_path else None
+        self.refresh_token_file_path = (
+            Path(refresh_token_file_path) if refresh_token_file_path else None
         )
         self.credentials = self._authenticate()
         self.client = self._get_graph_client(
@@ -272,20 +278,20 @@ def _load_token_from_file(self) -> Optional[str]:
         Returns:
             Optional[str]: Refresh token if file exists and valid, else None.
         """
-        if not self.token_file_path:
+        if not self.refresh_token_file_path:
             return None
 
-        if not self.token_file_path.exists():
+        if not self.refresh_token_file_path.exists():
             return None
 
         try:
-            with open(self.token_file_path, 'r') as f:
+            with open(self.refresh_token_file_path, 'r') as f:
                 token_data = json.load(f)
 
             refresh_token = token_data.get('refresh_token')
             if refresh_token:
                 logger.info(
-                    f"Refresh token loaded from {self.token_file_path}"
+                    f"Refresh token loaded from {self.refresh_token_file_path}"
                 )
                 return refresh_token
 
@@ -302,17 +308,21 @@ def _save_token_to_file(self, refresh_token: str):
         Args:
             refresh_token (str): The refresh token to save.
         """
-        if not self.token_file_path:
+        if not self.refresh_token_file_path:
             logger.info("Token file path not set, skipping token save")
             return
 
         try:
             # Create parent directories if they don't exist
-            self.token_file_path.parent.mkdir(parents=True, exist_ok=True)
+            self.refresh_token_file_path.parent.mkdir(
+                parents=True, exist_ok=True
+            )
 
-            with open(self.token_file_path, 'w') as f:
+            with open(self.refresh_token_file_path, 'w') as f:
                 json.dump({"refresh_token": refresh_token}, f, indent=2)
-            logger.info(f"Refresh token saved to {self.token_file_path}")
+            logger.info(
+                f"Refresh token saved to {self.refresh_token_file_path}"
+            )
         except Exception as e:
             logger.warning(f"Failed to save token to file: {e!s}")
 
@@ -342,7 +352,7 @@ def _authenticate_using_refresh_token(
             tenant_id=self.tenant_id,
             refresh_token=refresh_token,
             scopes=self.scopes,
-            token_file_path=self.token_file_path,
+            refresh_token_file_path=self.refresh_token_file_path,
         )
 
         logger.info("Authentication with saved token successful")
@@ -426,7 +436,8 @@ def _authenticate(self):
         """Authenticates and creates credential for Microsoft Graph.
 
         Implements two-stage authentication:
-        1. Attempts to use saved refresh token if token_file_path is provided
+        1. Attempts to use saved refresh token if refresh_token_file_path is
+            provided
         2. Falls back to browser OAuth if no token or token invalid
 
         Returns:
@@ -443,7 +454,10 @@ def _authenticate(self):
             self.client_secret = os.getenv("MICROSOFT_CLIENT_SECRET")
 
             # Try saved refresh token first if token file path is provided
-            if self.token_file_path and self.token_file_path.exists():
+            if (
+                self.refresh_token_file_path
+                and self.refresh_token_file_path.exists()
+            ):
                 try:
                     credentials: CustomAzureCredential = (
                         self._authenticate_using_refresh_token()
@@ -781,16 +795,16 @@ def get_tools(self) -> List[FunctionTool]:
                 representing the functions in the toolkit.
         """
         return [
-            FunctionTool(self.send_email),
-            FunctionTool(self.create_draft_email),
-            FunctionTool(self.send_draft_email),
-            FunctionTool(self.delete_email),
-            FunctionTool(self.move_message_to_folder),
-            FunctionTool(self.get_attachments),
-            FunctionTool(self.get_message),
-            FunctionTool(self.list_messages),
-            FunctionTool(self.reply_to_email),
-            FunctionTool(self.update_draft_message),
+            FunctionTool(run_async(self.send_email)),
+            FunctionTool(run_async(self.create_draft_email)),
+            FunctionTool(run_async(self.send_draft_email)),
+            FunctionTool(run_async(self.delete_email)),
+            FunctionTool(run_async(self.move_message_to_folder)),
+            FunctionTool(run_async(self.get_attachments)),
+            FunctionTool(run_async(self.get_message)),
+            FunctionTool(run_async(self.list_messages)),
+            FunctionTool(run_async(self.reply_to_email)),
+            FunctionTool(run_async(self.update_draft_message)),
         ]
 
     async def create_draft_email(

examples/toolkits/microsoft_outlook_mail_toolkit.py

@@ -0,0 +1,96 @@
+# ========= 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. =========
+
+
+from camel.agents import ChatAgent
+from camel.models import ModelFactory
+from camel.toolkits import OutlookMailToolkit
+from camel.types import ModelPlatformType
+from camel.types.enums import ModelType
+
+# Create a model instance
+model = ModelFactory.create(
+    model_platform=ModelPlatformType.DEFAULT,
+    model_type=ModelType.DEFAULT,
+)
+
+# Define system message for the Outlook assistant
+sys_msg = (
+    "You are a helpful Microsoft Outlook assistant that can help users manage "
+    "their emails. You have access to all Outlook tools including sending "
+    "emails, fetching emails, managing drafts, and more."
+)
+
+# Initialize the Outlook toolkit
+print("Initializing Outlook toolkit (browser may open for authentication)...")
+outlook_toolkit = OutlookMailToolkit()
+print("Outlook toolkit initialized!")
+
+# Get all Outlook tools
+all_tools = outlook_toolkit.get_tools()
+print(f"Loaded {len(all_tools)} Outlook tools")
+
+# Initialize a ChatAgent with all Outlook tools
+outlook_agent = ChatAgent(
+    system_message=sys_msg,
+    model=model,
+    tools=all_tools,
+)
+
+# Example: Send an email
+print("\nExample: Sending an email")
+print("=" * 50)
+
+user_message = (
+    "Send an email to [email protected] with subject "
+    "'Hello from Outlook Toolkit' and body 'This is a test email "
+    "sent using the CAMEL Outlook toolkit.'"
+)
+
+response = outlook_agent.step(user_message)
+print("Agent Response:")
+print(response.msgs[0].content)
+print("\nTool calls:")
+print(response.info['tool_calls'])
+
+"""
+Example: Sending an email
+==================================================
+Agent Response:
+Done  your message has been sent to [email protected].
+
+Tool calls:
+[ToolCallingRecord(
+    tool_name='send_email',
+    args={
+        'to_email': ['[email protected]'],
+        'subject': 'Hello from Outlook Toolkit',
+        'content': 'This is a test email sent using the CAMEL toolkit.',
+        'is_content_html': False,
+        'attachments': None,
+        'cc_recipients': None,
+        'bcc_recipients': None,
+        'reply_to': None,
+        'save_to_sent_items': True
+    },
+    result={
+        'status': 'success',
+        'message': 'Email sent successfully',
+        'recipients': ['[email protected]'],
+        'subject': 'Hello from Outlook Toolkit'
+    },
+    tool_call_id='call_abc123',
+    images=None
+)]
+"""