From b44d5b9604c31608794e39c8825835d17afd43ed Mon Sep 17 00:00:00 2001 From: Wendong Date: Thu, 13 Mar 2025 22:33:21 +0800 Subject: [PATCH] update readme and format fix --- README.md | 29 ++++++++++++++++++++++++++++- README_zh.md | 27 ++++++++++++++++++++++++++- owl/run_deepseek_zh.py | 6 ++---- owl/run_mcp.py | 29 +++++++++++++++++++++-------- owl/run_terminal.py | 7 +++++-- owl/run_terminal_zh.py | 12 ++++++++---- owl/utils/enhanced_role_playing.py | 9 ++++----- owl/utils/gaia.py | 4 +++- run_app.py | 3 ++- run_app_zh.py | 3 ++- 10 files changed, 101 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 13640ab..71de92e 100644 --- a/README.md +++ b/README.md @@ -122,7 +122,9 @@ https://private-user-images.githubusercontent.com/55657767/420212194-e813fc05-13 - **Browser Automation**: Utilize the Playwright framework for simulating browser interactions, including scrolling, clicking, input handling, downloading, navigation, and more. - **Document Parsing**: Extract content from Word, Excel, PDF, and PowerPoint files, converting them into text or Markdown format. - **Code Execution**: Write and execute Python code using interpreter. -- **Built-in Toolkits**: Access to a comprehensive set of built-in toolkits including ArxivToolkit, AudioAnalysisToolkit, CodeExecutionToolkit, DalleToolkit, DataCommonsToolkit, ExcelToolkit, GitHubToolkit, GoogleMapsToolkit, GoogleScholarToolkit, ImageAnalysisToolkit, MathToolkit, NetworkXToolkit, NotionToolkit, OpenAPIToolkit, RedditToolkit, SearchToolkit, SemanticScholarToolkit, SymPyToolkit, VideoAnalysisToolkit, WeatherToolkit, BrowserToolkit, and many more for specialized tasks. +- **Built-in Toolkits**: Access to a comprehensive set of built-in toolkits including: + - **Model Context Protocol (MCP)**: A universal protocol layer that standardizes AI model interactions with various tools and data sources + - **Core Toolkits**: ArxivToolkit, AudioAnalysisToolkit, CodeExecutionToolkit, DalleToolkit, DataCommonsToolkit, ExcelToolkit, GitHubToolkit, GoogleMapsToolkit, GoogleScholarToolkit, ImageAnalysisToolkit, MathToolkit, NetworkXToolkit, NotionToolkit, OpenAPIToolkit, RedditToolkit, SearchToolkit, SemanticScholarToolkit, SymPyToolkit, VideoAnalysisToolkit, WeatherToolkit, BrowserToolkit, and many more for specialized tasks # 🛠️ Installation @@ -275,6 +277,23 @@ For more detailed Docker usage instructions, including cross-platform support, o # 🚀 Quick Start +## Try MCP (Model Context Protocol) Integration + +Experience the power of MCP by running our example that demonstrates multi-agent information retrieval and processing: + +```bash +# Set up MCP servers (one-time setup) +npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude +npx @wonderwhy-er/desktop-commander setup + +# Run the MCP example +python owl/run_mcp.py +``` + +This example showcases how OWL agents can seamlessly interact with file systems, web automation, and information retrieval through the MCP protocol. Check out `owl/run_mcp.py` for the full implementation. + +## Basic Usage + After installation and setting up your environment variables, you can start using OWL right away: ```bash @@ -355,6 +374,14 @@ Here are some tasks you can try with OWL: # 🧰 Toolkits and Capabilities +## Model Context Protocol (MCP) + +OWL's MCP integration provides a standardized way for AI models to interact with various tools and data sources: + +Try our comprehensive MCP example in `owl/run_mcp.py` to see these capabilities in action! + +## Available Toolkits + > **Important**: Effective use of toolkits requires models with strong tool calling capabilities. For multimodal toolkits (Web, Image, Video), models must also have multimodal understanding abilities. OWL supports various toolkits that can be customized by modifying the `tools` list in your script: diff --git a/README_zh.md b/README_zh.md index b7fd579..c7e24dd 100644 --- a/README_zh.md +++ b/README_zh.md @@ -105,7 +105,7 @@ - **[2025.03.12]**: 在SearchToolkit中添加了Bocha搜索功能，集成了火山引擎模型平台，并更新了Azure和OpenAI Compatible模型的结构化输出和工具调用能力。 -- **[2025.03.11]**: 我们添加了 MCPToolkit、FileWriteToolkit 和 TerminalToolkit，增强 OWL Agent的工具调用、文件写入能力和终端命令执行功能。 +- **[2025.03.11]**: 我们添加了 MCPToolkit、FileWriteToolkit 和 TerminalToolkit，增强了 OWL Agent 的 MCP（模型上下文协议）集成、文件写入能力和终端命令执行功能。MCP 作为一个通用协议层，标准化了 AI 模型与各种数据源和工具的交互方式。 - **[2025.03.09]**: 我们添加了基于网页的用户界面，使系统交互变得更加简便。 - **[2025.03.07]**: 我们开源了 🦉 OWL 项目的代码库。 - **[2025.03.03]**: OWL 在 GAIA 基准测试中取得 58.18 平均分，在开源框架中排名第一！ @@ -272,6 +272,23 @@ chmod +x build_docker.sh 更多详细的Docker使用说明，包括跨平台支持、优化配置和故障排除，请参阅 [DOCKER_README.md](.container/DOCKER_README.md) # 🚀 快速开始 + +## 尝试 MCP（模型上下文协议）集成 + +体验 MCP 的强大功能，运行我们的示例来展示多智能体信息检索和处理： + +```bash +# 设置 MCP 服务器（仅需一次性设置） +npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude +npx @wonderwhy-er/desktop-commander setup + +# 运行 MCP 示例 +python owl/run_mcp.py +``` + +这个示例展示了 OWL 智能体如何通过 MCP 协议无缝地与文件系统、网页自动化和信息检索进行交互。查看 `owl/run_mcp.py` 了解完整实现。 + +## 基本用法 运行以下示例： @@ -349,6 +366,14 @@ OWL 将自动调用与文档相关的工具来处理文件并提取答案。 # 🧰 工具包与功能 +## 模型上下文协议（MCP） + +OWL 的 MCP 集成为 AI 模型与各种工具和数据源的交互提供了标准化的方式。 + +查看我们的综合示例 `owl/run_mcp.py` 来体验这些功能！ + +## 可用工具包 + > **重要提示**：有效使用工具包需要具备强大工具调用能力的模型。对于多模态工具包（Web、图像、视频），模型还必须具备多模态理解能力。 OWL支持多种工具包，可通过修改脚本中的`tools`列表进行自定义： diff --git a/owl/run_deepseek_zh.py b/owl/run_deepseek_zh.py index 52b4c34..0f14c58 100644 --- a/owl/run_deepseek_zh.py +++ b/owl/run_deepseek_zh.py @@ -31,7 +31,7 @@ from camel.toolkits import ( from camel.types import ModelPlatformType, ModelType -from utils import OwlRolePlaying, run_society, DocumentProcessingToolkit +from utils import OwlRolePlaying, run_society from camel.logger import set_log_level @@ -99,9 +99,7 @@ def construct_society(question: str) -> OwlRolePlaying: def main(): r"""Main function to run the OWL system with an example question.""" # Example research question - question = ( - "搜索OWL项目最近的新闻并生成一篇报告，最后保存到本地。" - ) + question = "搜索OWL项目最近的新闻并生成一篇报告，最后保存到本地。" # Construct and run the society society = construct_society(question) diff --git a/owl/run_mcp.py b/owl/run_mcp.py index a8b1d88..67849ee 100644 --- a/owl/run_mcp.py +++ b/owl/run_mcp.py @@ -1,3 +1,16 @@ +# ========= 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. ========= """MCP Multi-Agent System Example This example demonstrates how to use MCP (Model Context Protocol) with CAMEL agents @@ -15,7 +28,7 @@ Environment Setup: # Install MCP service npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude npx @wonderwhy-er/desktop-commander setup - + # Configure in owl/mcp_servers_config.json: { "desktop-commander": { @@ -33,7 +46,7 @@ Environment Setup: # Install MCP service npm install -g @executeautomation/playwright-mcp-server npx playwright install-deps - + # Configure in mcp_servers_config.json: { "mcpServers": { @@ -49,7 +62,7 @@ Environment Setup: ```bash # Install MCP service pip install mcp-server-fetch - + # Configure in mcp_servers_config.json: { "mcpServers": { @@ -92,7 +105,6 @@ from camel.toolkits import MCPToolkit from utils.enhanced_role_playing import OwlRolePlaying, run_society - load_dotenv() set_log_level(level="DEBUG") @@ -150,7 +162,7 @@ async def main(): question = ( "I'd like a academic report about Andrew Ng, including his research " - "direction, published papers (At least 3), institutions, etc." + "direction, published papers (At least 3), institutions, etc." "Then organize the report in Markdown format and save it to my desktop" ) @@ -164,8 +176,9 @@ async def main(): # Make sure to disconnect safely after all operations are completed. try: await mcp_toolkit.disconnect() - except Exception as e: - print(f"Warning: Error during disconnect: {e}") + except Exception: + print("Disconnect failed") + if __name__ == "__main__": - asyncio.run(main()) \ No newline at end of file + asyncio.run(main()) diff --git a/owl/run_terminal.py b/owl/run_terminal.py index 3741a7e..d77f33a 100644 --- a/owl/run_terminal.py +++ b/owl/run_terminal.py @@ -18,7 +18,7 @@ from camel.toolkits import ( SearchToolkit, BrowserToolkit, FileWriteToolkit, - TerminalToolkit + TerminalToolkit, ) from camel.types import ModelPlatformType, ModelType from camel.logger import set_log_level @@ -30,6 +30,7 @@ set_log_level(level="DEBUG") # Get current script directory base_dir = os.path.dirname(os.path.abspath(__file__)) + def construct_society(question: str) -> OwlRolePlaying: r"""Construct a society of agents based on the given question. @@ -113,7 +114,9 @@ def main(): answer, chat_history, token_count = run_society(society) # Output the result - print(f"\033[94mAnswer: {answer}\nChat History: {chat_history}\ntoken_count:{token_count}\033[0m") + print( + f"\033[94mAnswer: {answer}\nChat History: {chat_history}\ntoken_count:{token_count}\033[0m" + ) if __name__ == "__main__": diff --git a/owl/run_terminal_zh.py b/owl/run_terminal_zh.py index 2582c24..bbddc5b 100644 --- a/owl/run_terminal_zh.py +++ b/owl/run_terminal_zh.py @@ -12,13 +12,13 @@ # limitations under the License. # ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. ========= from dotenv import load_dotenv - +import os from camel.models import ModelFactory from camel.toolkits import ( SearchToolkit, BrowserToolkit, FileWriteToolkit, - TerminalToolkit + TerminalToolkit, ) from camel.types import ModelPlatformType, ModelType from camel.logger import set_log_level @@ -27,10 +27,12 @@ from utils import OwlRolePlaying, run_society load_dotenv() set_log_level(level="DEBUG") -import os + + # Get current script directory base_dir = os.path.dirname(os.path.abspath(__file__)) + def construct_society(question: str) -> OwlRolePlaying: r"""Construct a society of agents based on the given question. @@ -112,7 +114,9 @@ def main(): answer, chat_history, token_count = run_society(society) # Output the result - print(f"\033[94mAnswer: {answer}\nChat History: {chat_history}\ntoken_count:{token_count}\033[0m") + print( + f"\033[94mAnswer: {answer}\nChat History: {chat_history}\ntoken_count:{token_count}\033[0m" + ) if __name__ == "__main__": diff --git a/owl/utils/enhanced_role_playing.py b/owl/utils/enhanced_role_playing.py index fe14efe..f8cf045 100644 --- a/owl/utils/enhanced_role_playing.py +++ b/owl/utils/enhanced_role_playing.py @@ -282,8 +282,7 @@ Please note that our overall task may be very complicated. Here are some tips th ) async def astep( - self, - assistant_msg: BaseMessage + self, assistant_msg: BaseMessage ) -> Tuple[ChatAgentResponse, ChatAgentResponse]: user_response = await self.user_agent.astep(assistant_msg) if user_response.terminated or user_response.msgs is None: @@ -452,9 +451,9 @@ async def run_society( input_msg = society.init_chat(init_prompt) for _round in range(round_limit): assistant_response, user_response = await society.astep(input_msg) - overall_prompt_token_count += ( - assistant_response.info["usage"]["completion_tokens"] - ) + overall_prompt_token_count += assistant_response.info["usage"][ + "completion_tokens" + ] overall_prompt_token_count += ( assistant_response.info["usage"]["prompt_tokens"] + user_response.info["usage"]["prompt_tokens"] diff --git a/owl/utils/gaia.py b/owl/utils/gaia.py index a133a26..83e8744 100644 --- a/owl/utils/gaia.py +++ b/owl/utils/gaia.py @@ -191,7 +191,9 @@ class GAIABenchmark(BaseBenchmark): except Exception as e: logger.warning(e) # raise FileNotFoundError(f"{self.save_to} does not exist.") - datas = [data for data in datas if not self._check_task_completed(data["task_id"])] + datas = [ + data for data in datas if not self._check_task_completed(data["task_id"]) + ] logger.info(f"Number of tasks to be processed: {len(datas)}") # Process tasks for task in tqdm(datas, desc="Running"): diff --git a/run_app.py b/run_app.py index ccea485..69af092 100644 --- a/run_app.py +++ b/run_app.py @@ -22,7 +22,8 @@ import os import sys from pathlib import Path -os.environ['PYTHONIOENCODING'] = 'utf-8' +os.environ["PYTHONIOENCODING"] = "utf-8" + def main(): """Main function to launch the OWL Intelligent Assistant Platform""" diff --git a/run_app_zh.py b/run_app_zh.py index 0ec4e7b..4edc38b 100644 --- a/run_app_zh.py +++ b/run_app_zh.py @@ -22,7 +22,8 @@ import os import sys from pathlib import Path -os.environ['PYTHONIOENCODING'] = 'utf-8' +os.environ["PYTHONIOENCODING"] = "utf-8" + def main(): """主函数，启动OWL智能助手运行平台"""