【Agent】OpenManus-Tool 详细分析

1. Tool基础架构

1.1 BaseTool 抽象基类

BaseTool 是所有工具的基础抽象类，定义了工具的基本接口和行为。

class BaseTool(ABC, BaseModel):name: strdescription: strparameters: 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 = toolsself.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_DESCRIPTIONparameters: 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调用流程

1. Agent 接收用户输入
2. LLM 分析输入并决定使用哪个工具
3. Agent 通过 ToolCollection 查找并执行工具
4. 工具执行结果被添加到Agent 内存
5. LLM 基于结果决定下一步操作

设计理念：

• 清晰的责任分离
• 标准化的工具执行流程
• 结果处理的一致性

4.3 Tool扩展性

新工具可以通过以下步骤添加：

1. 继承 BaseTool 类并实现 execute 方法
2. 定义工具名称、描述和参数
3. 在 __init__.py 中导出工具
4. 在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 能够适应各种应用场景，从软件开发到信息检索，从任务规划到网页交互，提供全面而强大的自动化能力。