【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: 创建初始计划

调用逻辑：

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

2.6 SWEAgent (软件工程智能体)

设计特点：

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

关键属性：

max_step: 30

额外属性：

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

复写 think：

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

3. 智能体调用流程

3.1 初始化流程

智能体创建：

python 复制代码

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

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

3.2 执行流程

启动执行：
python 复制代码
```
result = await agent.run(prompt)
```
状态管理：
- 使用 state_context 将状态设置为 RUNNING
- 执行完成后恢复状态或设置为 FINISHED

执行循环：

复制代码

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

思考-行动循环：

复制代码

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

工具调用流程：

复制代码

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)

特殊工具处理：

复制代码

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

3.3 内存管理

消息添加：

python 复制代码

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

消息访问：

python 复制代码

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

3.4 工具集成

工具注册：

python 复制代码

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

工具执行：

python 复制代码

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 限制执行步骤
防止无限循环和资源耗尽