【Agent】OpenManus-Agent架构详细分析

各组件详细设计见：

• BaseAgent：BaseAgent
• ReActAgent：ReActAgent
• ToolCallAgent：ToolCallAgent
• 具体Agent实现：具体Agent
• Memory数据结构：Memory

1. 智能体层次结构

OpenManus 采用了一个多层次的智能体继承结构，形成了清晰的能力分层：

BaseAgent (抽象基类)
    ↓
ReActAgent (思考-行动循环)
    ↓
ToolCallAgent (工具调用能力)
    ↓
具体智能体实现:
    - Manus (通用智能体)
    - PlanningAgent (规划智能体)
    - SWEAgent (软件工程智能体)

2. 核心组件设计

2.1 BaseAgent (基础代理)

设计特点：

• 使用 Pydantic 支持数据验证和序列化
• 实现了状态管理、内存管理和执行循环的基础功能
• 提供了上下文管理器 state_context 用于安全的状态转换
• 实现了 run 方法作为主要执行入口
• 定义了 step 抽象方法，要求子类实现
• 包含循环检测和处理机制

关键属性：

• name: 智能体名称
• description: 智能体描述
• system_prompt: 系统级指令提示
• next_step_prompt: 下一步行动提示
• llm: 语言模型实例
• memory: 内存存储
• state: 当前状态
• max_steps: 最大步骤数
• current_step: 当前步骤

调用逻辑：

a. 通过 run 方法启动智能体

b. 使用 state_context 管理状态转换

c. 循环执行 step 方法直到达到终止条件

d. 检测并处理循环状态

e. 返回执行结果

2.2 ReActAgent (思考-行动代理)

设计特点：

• 实现了 ReAct (Reasoning and Acting) 模式
• 将 step 方法分解为 think 和 act 两个抽象方法
• 提供了思考-行动循环的基本框架

关键方法：

• think: 抽象方法，处理当前状态并决定下一步行动
• act: 抽象方法，执行决定的行动
• step: 实现了单个思考-行动周期

调用逻辑：

a. step 方法首先调用 think 方法

b. 如果 think 返回 True，则调用 act 方法

c. 返回执行结果

2.3 ToolCallAgent (工具调用代理)

设计特点：

• 扩展了 ReActAgent，专注于工具调用能力
• 实现了与 LLM 的工具调用接口集成
• 支持多种工具选择模式：none、auto、required
• 提供了工具执行和结果处理机制
• 支持特殊工具处理（如终止工具）

关键属性：

• available_tools: 可用工具集合
• tool_choices: 工具选择模式
• special_tool_names: 特殊工具名称列表
• tool_calls: 当前工具调用列表

关键方法：

• think: 这个方法的核心是与 LLM 交互，获取其决策，并根据不同的工具选择模式决定下一步操作

• act: 执行 LLM 决定使用的工具，并处理执行结果

  • 如果没有工具调用且工具选择模式为 ToolChoice.REQUIRED，则抛出异常

  • 如果没有工具调用，返回最后一条消息的内容

  • 对每个工具调用，执行 execute_tool 方法并获取结果

  • 如果设置了 max_observe，限制结果的长度

  • 记录工具执行完成的日志

  • 将工具响应添加到内存中

  • 返回所有结果的组合字符串

• execute_tool: 执行单个工具调用

• _handle_special_tool: 处理特殊工具执行

调用逻辑：

a. think 方法向 LLM 发送消息并获取响应

b. 解析响应中的工具调用

c. 将响应添加到内存中

d. act 方法执行工具调用

e. 处理工具执行结果

f. 检查特殊工具并更新状态

2.4 Manus (通用智能体)

设计特点：

• 继承自 ToolCallAgent，是项目的主要智能体
• 配置了多种工具：PythonExecute、WebSearch、BrowserUseTool、FileSaver、Terminate
• 使用特定的系统 prompt 和下一步 prompt
• 重写了特殊工具处理方法，确保浏览器资源清理

关键属性：

• max_observe: 限制 tool call的长度
• max_steps: 设置为 20 步

复写_handle_special_tool()：

• 检查工具是否为特殊工具
• 如果是特殊工具，清理浏览器资源
• 调用父类的 _handle_special_tool() 方法

2.5 PlanningAgent (规划智能体)

设计特点：

• 继承自 ToolCallAgent，专注于任务规划
• 使用 PlanningTool 创建和管理结构化计划
• 跟踪计划步骤的执行状态
• 支持计划创建、更新和执行

额外属性：

• active_plan_id: 当前活动计划的 ID
• step_execution_tracker: 步骤执行跟踪器
• current_step_index: 当前步骤索引

复写方法：

• run

  • 如果提供了请求，创建初始计划

  • 调用父类的 run() 方法

• think

  • 获取当前计划状态并添加到提示中
  • 获取当前步骤索引
  • 调用父类的 think() 方法
  • 将工具调用与当前步骤关联以进行跟踪

• act:

  • 调用父类的 act() 方法执行工具
  • 更新工具执行状态为已完成
  • 如果是非规划、非特殊工具，更新计划状态

额外实现方法

• get_plan: 获取当前计划

• update_plan_status: 更新计划状态

• _get_current_step_index(): 解析当前计划以识别第一个未完成步骤的索引

• create_initial_plan: 创建初始计划

调用逻辑：

1. 初始化时创建计划 ID 并验证工具
2. 首次运行时创建初始计划
3. 执行计划步骤并更新状态
4. 跟踪计划进度直到完成

2.6 SWEAgent (软件工程智能体)

设计特点：

• 继承自 ToolCallAgent，专注于软件工程任务
• 配置了 Bash、StrReplaceEditor 和 Terminate 工具
• 跟踪工作目录状态

关键属性：

• max_step: 30

额外属性：

• bash: Bash 工具实例
• working_dir: 当前工作目录

复写 think：

• 更新当前工作目录
• 使用当前工作目录格式化 next_step_prompt
• 调用父类的 think() 方法

3. 智能体调用流程

3.1 初始化流程

1. 智能体创建：

   agent = Manus()  # 或其他具体智能体
   

2. 初始化验证：

   • 通过 Pydantic 的 model_validator 进行初始化验证
   • 设置默认 LLM 和内存实例
   • 验证必要的工具和配置

3.2 执行流程

1. 启动执行：

   result = await agent.run(prompt)
   

2. 状态管理：

   • 使用 state_context 将状态设置为 RUNNING
   • 执行完成后恢复状态或设置为 FINISHED

3. 执行循环：

   while current_step < max_steps and state != FINISHED:
       current_step += 1
       step_result = await step()
       check_for_stuck_state()
   

4. 思考-行动循环：

   async def step():
       should_act = await think()
       if should_act:
           return await act()
   

5. 工具调用流程：

   async def think():
       response = await llm.ask_tool(messages, tools, tool_choice)
       parse_tool_calls(response)
       add_to_memory(response)
   
   async def act():
       for command in tool_calls:
           result = await execute_tool(command)
           add_to_memory(result)
   

6. 特殊工具处理：

   if tool_name in special_tool_names:
       if should_finish_execution():
           state = FINISHED
   

3.3 内存管理

1. 消息添加：

   agent.update_memory("user", "用户输入")
   agent.update_memory("assistant", "助手响应")
   agent.update_memory("tool", "工具结果", tool_call_id="工具ID")
   

2. 消息访问：

   messages = agent.messages  # 获取所有消息
   

3.4 工具集成

1. 工具注册：

   available_tools = ToolCollection(
       PythonExecute(), WebSearch(), BrowserUseTool(), FileSaver(), Terminate()
   )
   

2. 工具执行：

   result = await available_tools.execute(name="tool_name", tool_input=args)
   

4. 设计模式应用

4.1 模板方法模式

• BaseAgent 定义了算法骨架 (run)
• 子类实现特定步骤 (step, think, act)

4.2 策略模式

• 不同的智能体实现不同的策略
• 通过继承和多态实现策略选择

4.3 组合模式

• ToolCollection 管理多个工具
• 提供统一的接口执行工具

4.4 观察者模式

• 状态变化和事件处理
• 工具执行结果通知

4.5 命令模式

• 工具调用封装为命令对象
• 支持命令执行和结果处理

5. 扩展性设计

5.1 智能体扩展

• 可以通过继承 BaseAgent 或其子类创建新的智能体
• 只需实现必要的抽象方法

5.2 工具扩展

• 通过 ToolCollection 可以灵活添加新工具
• 智能体可以动态配置可用工具

5.3 提示词扩展

• 系统提示和下一步提示可以自定义
• 支持特定领域的提示词模板

6. 错误处理机制

6.1 异常捕获

• 在 think 和 act 方法中捕获异常
• 记录错误并添加到内存中

6.2 状态恢复

• 使用 state_context 确保状态正确恢复
• 异常时设置为 ERROR 状态

6.3 循环检测

• 实现了 is_stuck 方法检测重复响应
• 通过 handle_stuck_state 添加提示改变策略

7. 性能考虑

7.1 异步设计

• 所有关键方法都使用 async/await 实现
• 支持非阻塞 I/O 操作

7.2 资源管理

• 特殊工具处理确保资源清理
• 浏览器工具在终止时自动清理

7.3 步骤限制

• 通过 max_steps 限制执行步骤
• 防止无限循环和资源耗尽