enhance: feat: Lark integration closes #3571

Author: Wendong-Fan

camel/toolkits/lark_toolkit.py

@@ -15,7 +15,8 @@
 import json
 import os
 import time
-from typing import Dict, List, Literal, Optional, Union
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Literal, Optional, Union
 
 import requests
 
@@ -118,6 +119,78 @@ def _get_tenant_http_headers(self) -> Dict[str, str]:
             f"Failed to get tenant access token: {result.get('msg')}"
         )
 
+    def _convert_timestamp(self, ts: Any) -> str:
+        r"""Convert millisecond timestamp to readable datetime string.
+
+        Args:
+            ts: Timestamp value (can be string or int, in milliseconds).
+
+        Returns:
+            str: ISO format datetime string, or original value if conversion
+                fails.
+        """
+        try:
+            ts_int = int(ts)
+            # Convert milliseconds to seconds
+            dt = datetime.fromtimestamp(ts_int / 1000, tz=timezone.utc)
+            return dt.strftime("%Y-%m-%d %H:%M:%S UTC")
+        except (ValueError, TypeError, OSError):
+            return str(ts)
+
+    def _process_message_items(
+        self, items: List[Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        r"""Process message items to agent-friendly format.
+
+        Args:
+            items: List of message items from API response.
+
+        Returns:
+            List[Dict[str, Any]]: Simplified items with only essential fields.
+        """
+        processed = []
+        for item in items:
+            # Parse message content
+            text = ""
+            body = item.get("body", {})
+            content = body.get("content", "")
+            if content:
+                try:
+                    content_obj = json.loads(content)
+                    if "text" in content_obj:
+                        text = content_obj["text"]
+                    elif "template" in content_obj:
+                        # System message: render template
+                        tpl = content_obj["template"]
+                        for key in ["from_user", "to_chatters"]:
+                            val = content_obj.get(key, [])
+                            if val:
+                                tpl = tpl.replace(
+                                    "{" + key + "}", ", ".join(val)
+                                )
+                            else:
+                                tpl = tpl.replace("{" + key + "}", "")
+                        text = tpl.strip()
+                    elif "image_key" in content_obj:
+                        text = f"[Image: {content_obj['image_key']}]"
+                    elif "file_key" in content_obj:
+                        text = f"[File: {content_obj['file_key']}]"
+                except (json.JSONDecodeError, TypeError):
+                    text = content
+
+            # Build simplified message
+            sender = item.get("sender", {})
+            msg = {
+                "message_id": item.get("message_id"),
+                "msg_type": item.get("msg_type"),
+                "text": text,
+                "time": self._convert_timestamp(item.get("create_time", "")),
+                "sender_id": sender.get("id") or None,
+                "sender_type": sender.get("sender_type") or None,
+            }
+            processed.append(msg)
+        return processed
+
     def lark_list_chats(
         self,
         sort_type: Literal["ByCreateTimeAsc", "ByActiveTimeDesc"] = (
@@ -174,7 +247,18 @@ def lark_list_chats(
                     "code": result.get("code"),
                 }
 
-            return result
+            # Simplify chat items
+            data = result.get("data", {})
+            items = data.get("items", [])
+            simplified = [
+                {"chat_id": c.get("chat_id"), "name": c.get("name", "")}
+                for c in items
+            ]
+            return {
+                "chats": simplified,
+                "has_more": data.get("has_more", False),
+                "page_token": data.get("page_token", ""),
+            }
 
         except Exception as e:
             logger.error(f"Error listing chats: {e}")
@@ -259,7 +343,14 @@ def lark_get_chat_messages(
                     "code": result.get("code"),
                 }
 
-            return result
+            # Process and simplify messages
+            data = result.get("data", {})
+            items = data.get("items", [])
+            return {
+                "messages": self._process_message_items(items),
+                "has_more": data.get("has_more", False),
+                "page_token": data.get("page_token", ""),
+            }
 
         except Exception as e:
             logger.error(f"Error getting chat messages: {e}")
@@ -370,7 +461,12 @@ def lark_get_message_resource_key(
                 }
 
             data = result.get("data", {}) or {}
-            body = data.get("body", {}) or {}
+            items = data.get("items", []) or []
+            if not items:
+                return {"error": "No message found."}
+            # Get the first message item
+            item = items[0]
+            body = item.get("body", {}) or {}
             content = body.get("content", "")
             if not content:
                 return {"error": "Message content is empty."}

examples/toolkits/lark_toolkit_example.py

@@ -34,37 +34,41 @@
     tools=toolkit.get_tools(),
 )
 
-# Example: Chat and message operations
+# Example 1: List all chats
 print("=" * 60)
-print("Lark Toolkit Example: Chat and Message Operations")
+print("Example 1: List all chats the bot belongs to")
 print("=" * 60)
 
-response = agent.step(
-    "List all chats I belong to, get the recent messages from the first chat, "
-    "and if there are any images or files, download one of them."
-)
-print(f"Agent response: {response.msgs[0].content}")
+response = agent.step("List all chats I belong to.")
+print(f"Response: {response.msgs[0].content}\n")
 
-"""
-==========================================================================
-Example output:
+# Example 2: Get messages from a specific chat
+print("=" * 60)
+print("Example 2: Get recent messages from a chat")
+print("=" * 60)
 
-I've completed the Lark messaging tasks. Here's a summary:
+response = agent.step(
+    "Get the 5 most recent messages from the first chat, "
+    "sorted by newest first."
+)
+print(f"Response: {response.msgs[0].content}\n")
 
-1. **Listed Chats**: Found 3 chats you belong to:
-   - "Engineering Team" (group) - Chat ID: oc_xxx
-   - "Project Alpha" (group) - Chat ID: oc_yyy
-   - "John Doe" (p2p) - Chat ID: oc_zzz
+# Example 3: Download a resource from a message
+print("=" * 60)
+print("Example 3: Download image/file from a message")
+print("=" * 60)
 
-2. **Retrieved Messages**: Got recent messages from "Engineering Team":
-   - Found 15 messages in the chat
-   - Messages include text discussions and file attachments
+response = agent.step(
+    "If there are any images or files in the messages, "
+    "get the resource key and download one of them."
+)
+print(f"Response: {response.msgs[0].content}\n")
 
-3. **Downloaded Resource**: Found and downloaded an image:
-   - Message ID: om_xxx
-   - File Key: img_v2_xxx
-   - Content Type: image/png
-   - Saved to: ./workspace/lark_file/img_v2_xxx
+# Example 4: Direct toolkit usage (without agent)
+print("=" * 60)
+print("Example 4: Direct toolkit usage")
+print("=" * 60)
 
-==========================================================================
-"""
+# List chats directly
+result = toolkit.lark_list_chats(page_size=10)
+print(f"lark_list_chats result: {result}")

test/toolkits/test_lark_toolkit.py

@@ -106,8 +106,9 @@ def test_lark_list_chats(lark_toolkit):
 
         result = lark_toolkit.lark_list_chats()
 
-        assert result["code"] == 0
-        assert len(result["data"]["items"]) == 1
+        assert len(result["chats"]) == 1
+        assert result["chats"][0]["chat_id"] == "oc_1"
+        assert result["chats"][0]["name"] == "Team"
         mock_get.assert_called_once()
 
 
@@ -128,9 +129,9 @@ def test_lark_get_chat_messages(lark_toolkit):
 
         result = lark_toolkit.lark_get_chat_messages(container_id="oc_123")
 
-        assert result["code"] == 0
-        assert len(result["data"]["items"]) == 1
-        assert result["data"]["has_more"] is False
+        assert len(result["messages"]) == 1
+        assert result["messages"][0]["message_id"] == "msg_1"
+        assert result["has_more"] is False
 
 
 def test_lark_get_chat_messages_time_filters(lark_toolkit):
@@ -157,8 +158,8 @@ def test_lark_get_chat_messages_time_filters(lark_toolkit):
             sort_type="ByCreateTimeAsc",
         )
 
-        assert len(result["data"]["items"]) == 1
-        assert result["data"]["has_more"] is True
+        assert len(result["messages"]) == 1
+        assert result["has_more"] is True
 
         call_args = mock_get.call_args
         params = call_args[1]["params"]
@@ -206,7 +207,9 @@ def test_lark_get_message_resource_key(lark_toolkit):
         mock_get.return_value.json.return_value = {
             "code": 0,
             "data": {
-                "body": {"content": ("{\"image_key\":\"img_v3_02tb_abc\"}")}
+                "items": [
+                    {"body": {"content": '{"image_key":"img_v3_02tb_abc"}'}}
+                ]
             },
         }