OpenManus源码分析-Agent

概述

Agent为Open Manus里的最核心模块，Agent模块通过大模型自主使用各种工具，完成用户的各种需求。
Open Manus总体架构分析：OpenManus源码架构分析
Agent结构：

可以看到，所有Agent实现都是继承自ToolCallAgent，下面我们分别介绍一下每个Agent父类。

Agent模块类图

初始化阶段时序图

运行阶段时序图

BaseAgent

BaseAgent是基础Agent抽象模板类，提供了构建智能代理所需的基础框架，和run方法，用于启动Agent，其中使用抽象方法step供子类实现。step方法来定义具体的Agent行为。

核心属性

• name：智能体名称
• description: 智能体描述
• system_prompt: 系统级提示词
• next_step_prompt: 下一步动作提示词
• llm: 语言模型实例
• memory: 记忆存储，依旧是Agent执行step中，与大模型交互上下文。
• state: 当前状态

	### BaseAgent的state属性，标识目前Agent的运行状态
    state: AgentState = Field(
        default=AgentState.IDLE, description="Current agent state"
    )
    ### AgentState

• max_steps：最大步骤，限制Agent执行的最大step。
• current_step：记录当前step。
• duplicate_threshold：循环阈值，记录大模型回答是否重复，如果到达重复阈值，直接退出。

核心功能

• 状态管理
• 核心执行
• 循环检测
• 上下文管理

核心方法

initialize_agent（初始化方法）

initialize_agent()为BaseAgent中的初始化构造方法，在对象初始化后执行。

    @model_validator(mode="after")
    def initialize_agent(self) -> "BaseAgent":
    	// 根据配置初始化LLM对象
        if self.llm is None or not isinstance(self.llm, LLM):
            self.llm = LLM(config_name=self.name.lower())
        // 初始化memory，用于存储大模型上下文
        if not isinstance(self.memory, Memory):
            self.memory = Memory()
        return self

update_memory（上下文管理）

update_memory()用于更新大模型交互上下文，将上下文prompt分为user，system，assistant，tool。

    def update_memory(
        self,
        role: ROLE_TYPE,  # type: ignore
        content: str,
        base64_image: Optional[str] = None,
        **kwargs,
    ) -> None:
        message_map = {
            "user": Message.user_message,
            "system": Message.system_message,
            "assistant": Message.assistant_message,
            "tool": lambda content, **kw: Message.tool_message(content, **kw),
        }
        // 将tool返回的结果，以及大模型的提示词以及返回结果存储在memory中。
        self.memory.add_message(message_map[role](content, **kwargs))
     // ........

run（Agent任务执行）

run方法为Agent中最为核心的一个方法，里面定义了Agent的执行流程。

 async def run(self, request: Optional[str] = None) -> str:
        // 判断Agent State
        if self.state != AgentState.IDLE:
            raise RuntimeError(f"Cannot run agent from state: {self.state}")
        // 将用户提示词更新到上下文内存中
        if request:
            self.update_memory("user", request)
        results: List[str] = []
       	// 循环执行step，如果到达最大步数，或者Agent状态为Finished，则终止。
        async with self.state_context(AgentState.RUNNING):
            while (
                self.current_step < self.max_steps and self.state != AgentState.FINISHED
            ):
                self.current_step += 1
                step_result = await self.step()
                // 检查每个循环大模型回答是否重复，如果超过重复阈值，执行handle_stuck_state
                if self.is_stuck():
                    self.handle_stuck_state()
                results.append(f"Step {self.current_step}: {step_result}")
            // 如果执行步数超过最大步数，将Agent状态修改为空闲
            if self.current_step >= self.max_steps:
                self.current_step = 0
                self.state = AgentState.IDLE
                results.append(f"Terminated: Reached max steps ({self.max_steps})")
        await SANDBOX_CLIENT.cleanup()
        return "\n".join(results) if results else "No steps executed"

step

Step方法在BaseAgent中定义的抽象方法，为Agent多步执行的具体方法。

    @abstractmethod
    async def step(self) -> str:
        """Execute a single step in the agent's workflow.

        Must be implemented by subclasses to define specific behavior.
        """

ReactAgent

ReActAgent是一个基于"思考-行动"循环的专用Agent框架，它继承自BaseAgent，专注于提供结构化的推理和行动能力。“ReAct"来源于"Reasoning and Acting”（推理与行动），这一设计使Agent能够先思考再行动，模拟人类解决问题的方式。

基本功能

• 思考-行动分离设计： 将问题解决过程明确分为"思考"(think)和"行动"(act)两个独立阶段，使决策过程更加清晰。
• 灵活的推理实现： 允许开发者自定义思考逻辑，可以根据不同任务场景定制推理过程。
• 工具调用框架： 为工具调用提供了良好的抽象接口，使Agent能够方便地使用外部工具解决问题。

核心方法

step

 async def step(self) -> str:
       """Execute a single step: think and act."""
       should_act = await self.think()
       if not should_act:
           return "Thinking complete - no action needed"
       return await self.act()

实现了BaseAgent中的抽象方法，它协调think()和act()的调用流程。先调用think()方法进行推理，如果返回True表示需要行动，则调用act()方法执行具体操作。

think

   @abstractmethod
   async def think(self) -> bool:
       """Process current state and decide next action"""

这是ReActAgent独有的抽象方法，负责分析当前状态并决定下一步行动。返回一个布尔值，表示是否需要执行行动。子类必须实现此方法来定义具体的推理逻辑。

act

   @abstractmethod
   async def act(self) -> str:
       """Execute decided actions"""

这也是ReActAgent独有的抽象方法，负责执行具体行动。一般情况下，act()方法会调用工具或执行操作，然后返回执行结果。子类必须实现此方法来定义具体的行动逻辑。

ToolCallAgent

ToolCallAgent是ReActAgent的具体实现，专门设计用于处理复杂的工具调用场景。它扩展了ReActAgent的思考-行动模式，增加了丰富的工具管理和执行功能。这个代理能够动态选择合适的工具，执行工具调用，并处理工具返回的结果，适用于需要多种外部工具协作完成的复杂任务。

关键属性

• available_tools：可用工具集合，默认包含CreateChatCompletion和Terminate工具
• tool_choices：工具选择模式，可以是AUTO、REQUIRED或NONE，默认为AUTO。
• special_tool_names：特殊工具名称列表，这些工具可能会改变代理状态。
• tool_calls：当前步骤的工具调用列表。
• max_steps：最大执行步数，默认为30。

基本功能

• 工具集合管理：支持多种工具的注册、管理和调用，默认包含CreateChatCompletion和Terminate等基础工具。
• 灵活的工具选择模式：支持AUTO、REQUIRED和NONE三种工具选择模式，可以根据需要调整智能体使用工具的方式。
• 工具调用执行：能够解析工具参数，调用相应工具，处理执行结果，并将结果纳入记忆系统。
• 特殊工具处理：对某些特殊工具（如Terminate）提供专门处理机制，可以影响代理的执行状态。
• 资源自动清理：提供资源清理机制，确保工具使用的资源能够正确释放。

关键方法

ToolCallAgent实现了ReActAgent的抽象方法，并增加了一些特有方法：

think

async def think(self) -> bool:
       # 处理提示
       # 获取LLM响应（包含工具选择）
       # 记录工具调用决策
       # 处理不同工具选择模式
       # 将决策添加到记忆
       return bool(self.tool_calls or content)

act

   async def act(self) -> str:
       # 检查是否有工具调用
       # 依次执行每个工具调用
       # 处理和记录执行结果
       return "\n\n".join(results)

execute_tool

   async def execute_tool(self, command: ToolCall) -> str:
       # 验证工具命令
       # 解析工具参数
       # 执行工具
       # 处理特殊工具
       # 格式化执行结果
       return observation

这个特有方法处理单个工具的调用过程，包括参数解析、工具执行和结果处理。

_handle_special_tool

   async def _handle_special_tool(self, name: str, result: Any, **kwargs):
       # 检查是否为特殊工具
       # 根据需要更改Agent状态

这个方法专门处理特殊工具（如Terminate），可能会根据工具执行结果改变Agent的状态。