【Agent】OpenManus-Tool 详细分析
1. Tool基础架构
1.1 BaseTool 抽象基类
BaseTool 是所有工具的基础抽象类，定义了工具的基本接口和行为。
class BaseTool(ABC, BaseModel):
name: str
description: str
parameters: Optional[dict] = None
核心属性：
name：工具的唯一标识符description：工具功能描述，用于 LLM 理解工具用途parameters：JSON Schema 格式的参数定义
核心方法：
__call__：允许工具实例像函数一样被调用execute：抽象方法，所有子类必须实现的工具执行逻辑to_param：将工具转换为 LLM 函数调用格式
设计理念：
- 使用 Pydantic 模型确保类型安全
- 采用抽象类强制子类实现核心功能
- 提供统一接口简化工具调用
1.2 Tool结果类
ToolResult
class ToolResult(BaseModel):
output: Any = Field(default=None)
error: Optional[str] = Field(default=None)
system: Optional[str] = Field(default=None)
核心属性：
output：工具执行的主要输出error：错误信息（如果有）system：系统级消息（如日志或调试信息）
核心方法：
__bool__：允许将结果用于布尔条件判断__add__：支持结果组合__str__：提供字符串表示replace：创建修改后的结果副本
设计理念：
- 分离正常输出和错误信息
- 支持结果组合和转换
- 提供丰富的操作接口
特殊结果类型
class CLIResult(ToolResult):
"""A ToolResult that can be rendered as a CLI output."""
class ToolFailure(ToolResult):
"""A ToolResult that represents a failure."""
设计理念：
- 通过继承提供特定上下文的结果类型
- 允许根据结果类型进行特殊处理
1.3 AgentAwareTool
class AgentAwareTool:
agent: Optional = None
设计理念：
- 提供工具与Agent 交互的接口
- 允许工具访问Agent 状态和功能
2. Tool集合管理
ToolCollection 类
ToolCollection 负责管理多个工具，提供统一的访问和执行接口。
class ToolCollection:
def __init__(self, *tools: BaseTool):
self.tools = tools
self.tool_map = {tool.name: tool for tool in tools}
核心方法：
to_params：将所有工具转换为 LLM 可用的参数格式execute：根据名称执行特定工具execute_all：顺序执行所有工具get_tool：根据名称获取工具实例add_tool/add_tools：添加新工具到集合
设计理念：
- 提供工具的集中管理
- 支持动态添加和查找工具
- 简化工具执行流程
3. 核心Tool实现
3.1 终止工具 (Terminate)
class Terminate(BaseTool):
name: str = "terminate"
description: str = _TERMINATE_DESCRIPTION
parameters: dict = {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "The finish status of the interaction.",
"enum": ["success", "failure"],
}
},
"required": ["status"],
}
功能：结束Agent 执行，完成任务。
参数：
status：终止状态（“success” 或 “failure”）
设计理念：
- 提供明确的任务结束机制
- 支持成功/失败状态区分
- 作为特殊工具被Agent 识别
3.2 Python 执行工具 (PythonExecute)
功能：安全地执行 Python 代码字符串。
核心特性：
- 使用多进程隔离执行环境
- 实现超时控制防止无限循环
- 捕获标准输出和错误
- 支持变量持久化
设计理念：
- 平衡安全性和功能性
- 提供隔离的执行环境
- 支持复杂代码执行
3.3 浏览器工具 (BrowserUseTool)
功能：提供浏览器自动化能力。
核心特性：
- 支持网页导航、点击、输入等操作
- 支持多标签页管理
- 支持截图和内容提取
- 支持 JavaScript 执行
设计理念：
- 提供完整的网页交互能力
- 使用异步操作提高性能
- 实现资源清理确保系统稳定
3.4 文件保存工具 (FileSaver)
功能：将内容保存到本地文件。
核心特性：
- 支持写入和追加模式
- 自动创建目录结构
- 使用异步文件操作
设计理念：
- 提供简单直观的文件操作接口
- 确保文件操作的安全性
- 支持各种内容类型的保存
3.5 Web 搜索工具 (WebSearch)
功能：执行网络搜索并返回结果。
核心特性：
- 支持多种搜索引擎
- 可配置结果数量和格式
- 使用异步操作提高性能
设计理念：
- 提供外部信息获取能力
- 支持多种搜索源增强结果多样性
- 优化结果格式便于 LLM 处理
3.6 Bash 工具
功能：执行系统命令。
核心特性：
- 支持多命令执行
- 内部处理 cd 命令维护目录状态
- 提供命令清理和安全检查
设计理念：
- 提供系统级操作能力
- 确保命令执行安全
- 维护执行环境状态
3.7 字符串替换编辑器 (StrReplaceEditor)
功能：编辑文本文件。
核心特性：
- 支持文件读取和写入
- 支持内容替换和修改
- 提供文件操作的抽象
设计理念：
- 简化文件编辑操作
- 提供安全的文件修改机制
- 支持代码生成和修改场景
3.8 规划工具(Planning)
功能：PlanningTool 提供了完整的计划生命周期管理功能，内存存储多个 plan
-
创建包含标题和步骤的结构化计划
-
更新现有计划的内容和步骤
-
列出所有可用计划及其进度
-
获取特定计划的详细信息
-
设置活动计划以简化操作
-
标记步骤状态（未开始、进行中、已完成、已阻塞）
-
为步骤添加注释
-
删除不再需要的计划
核心特性
-
计划创建与管理
-
多计划支持：同时管理多个独立计划
-
唯一标识符：每个计划都有唯一的 ID
-
活动计划概念：设置当前活动计划简化操作
-
计划删除：支持删除不再需要的计划
-
-
步骤跟踪
-
状态管理：支持四种步骤状态（未开始、进行中、已完成、已阻塞）
-
步骤注释：为每个步骤添加详细说明或进度记录
-
状态可视化：使用符号标记（[ ]、[→]、[✓]、[!]）直观显示步骤状态
-
智能状态保留：更新计划时保留未变更步骤的状态
-
-
进度统计
-
完成率计算：自动计算计划完成百分比
-
状态统计：提供各状态步骤数量的统计信息
-
格式化输出：生成结构化的计划视图，包括进度和状态信息
-
设计理念
-
结构化任务分解
-
将复杂任务分解为可管理的步骤
-
提供清晰的执行路径和进度跟踪
-
支持任务的逐步完成和状态更新
-
-
状态持久化
-
在内存中维护计划数据结构
-
保存步骤状态和注释信息
-
在更新计划时智能保留状态信息
-
-
用户友好输出
-
提供格式化的计划视图
-
使用符号标记直观表示步骤状态
-
包含详细的进度统计和完成率
-
4. Tool集成架构
4.1 Tool注册与发现
工具通过 __init__.py 文件导出，并在Agent 类中注册：
from app.tool.base import BaseTool
from app.tool.bash import Bash
from app.tool.create_chat_completion import CreateChatCompletion
from app.tool.planning import PlanningTool
from app.tool.str_replace_editor import StrReplaceEditor
from app.tool.terminate import Terminate
from app.tool.tool_collection import ToolCollection
设计理念：
- 使用显式导入提高代码可读性
- 支持模块化组织和发现
- 便于新工具的添加和集成
4.2 Tool调用流程
- Agent 接收用户输入
- LLM 分析输入并决定使用哪个工具
- Agent 通过 ToolCollection 查找并执行工具
- 工具执行结果被添加到Agent 内存
- LLM 基于结果决定下一步操作
设计理念：
- 清晰的责任分离
- 标准化的工具执行流程
- 结果处理的一致性
4.3 Tool扩展性
新工具可以通过以下步骤添加：
- 继承 BaseTool 类并实现 execute 方法
- 定义工具名称、描述和参数
- 在
__init__.py中导出工具 - 在Agent 的 available_tools 中注册工具
设计理念：
- 低耦合的模块化设计
- 标准化的接口定义
- 简单直观的扩展机制
5. Tool安全性考虑
5.1 执行隔离
- Python 执行工具使用多进程隔离
- 浏览器工具使用独立的浏览器上下文
- Bash 工具提供命令验证和清理
5.2 资源限制
- 实现超时控制防止无限执行
- 限制文件操作的范围和权限
- 控制网络请求的频率和目标
5.3 错误处理
- 所有工具提供统一的错误报告机制
- 使用 try-except 块捕获和处理异常
- 详细记录错误信息便于调试
6. Tool性能优化
6.1 异步设计
所有工具都使用异步方法实现：
async def execute(self, **kwargs) -> Any:
"""Execute the tool with given parameters."""
设计理念：
- 提高系统整体响应性
- 支持并发操作
- 避免阻塞主线程
6.2 资源管理
- 实现资源获取和释放的配对操作
- 使用上下文管理器确保资源正确释放
- 实现清理方法处理异常情况
6.3 缓存机制
- 支持结果缓存减少重复操作
- 实现会话状态持久化
- 优化频繁使用的操作
7. Agent与Tool集成示例
7.1 SWEAgent 工具集成
available_tools: ToolCollection = ToolCollection(
Bash(), StrReplaceEditor(), Terminate()
)
设计理念：
- 专注于软件开发任务
- 提供命令行和文件编辑能力
- 保持工具集简洁高效
7.2 Manus 工具集成
available_tools: ToolCollection = Field(
default_factory=lambda: ToolCollection(
PythonExecute(), WebSearch(), BrowserUseTool(), FileSaver(), Terminate()
)
)
设计理念：
- 提供多样化的工具集
- 支持信息获取和处理
- 实现广泛的任务处理能力
7.3 PlanningAgent 工具集成
available_tools: ToolCollection = Field(
default_factory=lambda: ToolCollection(PlanningTool(), Terminate())
)
设计理念：
- 专注于任务规划和管理
- 简化工具集减少复杂性
- 通过规划提高任务执行效率
8. Tool系统设计原则总结
8.1 模块化设计
- 每个工具都是独立的模块
- 工具之间通过标准接口交互
- 支持独立开发和测试
8.2 统一接口
- 所有工具实现相同的基本接口
- 结果使用统一的数据结构
- 错误处理遵循一致的模式
8.3 可扩展性
- 支持动态添加新工具
- 工具参数使用灵活的 JSON Schema
- Agent 可以根据需要选择工具子集
8.4 安全与性能平衡
- 实现必要的安全措施
- 优化性能关键路径
- 提供适当的资源管理
结论
OpenManus 的工具系统是一个设计精良的模块化架构，它通过标准化的接口、灵活的组合和安全的执行环境，使 AI Agent 能够与外部世界交互，执行各种复杂任务。系统的核心优势在于其可扩展性和一致性，允许轻松添加新工具同时保持整体架构的完整性。
每个工具都有明确的职责和接口，可以独立开发和测试，同时又能无缝集成到整个系统中。这种设计使 OpenManus 能够适应各种应用场景，从软件开发到信息检索，从任务规划到网页交互，提供全面而强大的自动化能力。