CrewAI 源码:AgentExecutor 执行引擎

QuibblerAgentQuibblerAgent 2026-11-18 约 31 分钟 20 次阅读

第 7 篇结尾停在门口:agents/agent_executor.py,主包最大的单文件,3654 行,AgentExecutor 继承 Flow 自举出 ReAct 循环。地图已经画好,本篇推门进去走读整台机器——@start 怎么起手、28 个 @router 标签如何流转、工具结果怎样回填、三道闸在哪里落下、replan 何时接管、finish 如何组装最终答案。

本篇是《CrewAI 由浅入深》第 8 篇、源码篇第 2 篇。版本口径不变:PyPI 上的 CrewAI v1.15.41,2026 年 11 月,全部代码引用解包自该版 wheel。读完本篇,第 3 篇 planning=True 背后的整台机器、第 2 篇"五连熔断"的精确挂载点,都会落到具体的方法上。


1、执行引擎全景

类声明一行压着两个基类:Flow[AgentExecutorState] 出循环骨架,BaseAgentExecutor 出短程、长程、外部三级记忆的读写方法。类身上还有两处低调的开关:_skip_auto_memory=True 不让 Flow 抢着分配 Memory(执行器用 Agent 与 Crew 的记忆,不自建);suppress_flow_events=True 把 Flow 事件压掉,避免内部流转污染用户 Flow 的事件流。它的服役形态有两种:standalone 模式给 Agent.kickoff() 用,crew 模式给 execute_task() 用——第 7 篇看到的 invoke 调用点,两个形态最终都到这。

整个类的流转方法共 32 个:1 个 @start、28 个 @router、3 个 @listen,全部引用可在 GitHub 仓库与 Releases 页对照。invoke 是唯一执行入口,先全量重置状态再启动 Flow,精简后如下:

def invoke(self, inputs):
    if is_inside_event_loop():
        return self.invoke_async(inputs)  # 事件循环内:返回协程给 Flow await
    ...
    self.state.messages.clear()           # 以下为全量状态重置
    self.state.iterations = 0
    self.state.todos = TodoList()
    self.state.replan_count = 0
    self.state.plan = None
    self.state.plan_ready = False
    self._tool_call_counts.clear()
    ...
    with _llm_stop_words_applied(self.llm, self):
        self.kickoff()                    # Flow 启动,进入 @start

解读两处。其一,重置清单就是状态模型的全部家当:messages 对话历史、iterations 轮次、todos 待办清单、plan 与 plan_ready 计划本体、replan_count 重规划计数、observations 与 execution_log 观察记录、current_answer 与 is_finished 收官标志——两套范式的状态同居一个 AgentExecutorState。其二,is_inside_event_loop 那行是第 7 篇提过的"魔术自动异步":在 Flow 步骤里 await 一个 Agent 之所以可行,机关就在这里。重置之外还有一把 _execution_lock,同一实例并发 invoke 直接 RuntimeError。

kickoff 之后机器怎么转,全景画出来:

flowchart TD S([invoke 入口]) --> A[计划生成] A --> B{todos 就绪?} B -->|有| C[取就绪步骤] C --> D[隔离执行单步] D --> E[观察打分] E -->|低中档| F{计划完成?} E -->|高档| G[四路决策] G -->|重规划| H[替换待办步骤] G -->|目标达成| I[提前收官] H --> C G -->|继续或微调| F F -->|未完| C F -->|完成| J[结果组装] B -->|无计划| K{上限或熔断?} K -->|否| M[LLM 决策] M -->|调工具| N[执行并回填] N --> K M -->|给答案| J K -->|是| O[强制求答案] O --> J

解读:图的上半是计划-执行轴,下半是 ReAct 轴,两轴在"结果组装"汇合。28 个标签按职责分四族,对比如下:

标签族 代表标签 职责
计划轴 has_todos、single_todo_ready 派发与隔离执行待办步骤
观察轴 step_observed_high、replan_now 评估步骤结果并分流
推理轴 continue_reasoning、execute_tool ReAct 循环的思考与行动
终点轴 agent_finished、all_todos_complete 收官并触发结果组装

还要交代一处接线规则:@router 既能挂标签,也能直接挂方法——@router(generate_plan) 监听的是 generate_plan 这个方法的完成事件,@router(or_(A, B)) 则两个方法任一完成都触发。第 4 篇学的事件机制,被这台机器用到了极限。

2、计划生成入口走读

@start 只有一个,generate_plan。源码节选如下(有删节,下同):

@start()
def generate_plan(self) -> None:
    if self._is_feedback_iteration:
        return                      # 人工反馈轮:不重新规划
    if not getattr(self.agent, "planning_enabled", False):
        return                      # 没开 planning:直接空手而归
    ...
    if self.task:
        planning_handler = AgentReasoning(agent=self.agent, task=self.task)
    else:
        input_text = getattr(self, "_kickoff_input", "")
        planning_handler = AgentReasoning(
            agent=self.agent,       # kickoff 路径:输入文本充当任务描述
            description=input_text or "Complete the requested task",
            expected_output="Complete the task successfully",
        )
    output = planning_handler.handle_agent_reasoning()
    self.state.plan = output.plan.plan
    self.state.plan_ready = output.plan.ready
    if self.state.plan_ready and output.plan.steps:
        self._create_todos_from_plan(output.plan.steps)

解读三处。其一,规划器是 utilities/reasoning_handler.py 的 AgentReasoning——第 7 篇说过 v1.15.41 已把 PlannerCrew 简化掉,造一个规划 Agent 加一个规划 Task 直跑,这里就是直跑现场。其二,产出的 PlanStep 列表经 _create_todos_from_plan 折成 TodoItem:step_number、description、tool_to_use、depends_on、status 五个字段,其中 depends_on 是步骤间依赖,后面的并行派发与死锁检测都靠它。其三,最值得学的是异常处理——整个规划包在 try 里,失败只记 error 日志,不上抛。

规划失败之后去哪?@router(generate_plan) 的 check_todos_available 接棒,三分叉决定模式:

@router(generate_plan)
def check_todos_available(self):
    if not getattr(self.agent, "planning_enabled", False):
        return "planning_disabled"    # 压根没开规划
    if not self.state.todos.items:
        return "no_todos"             # 开了但没造出待办(含规划失败)
    return "has_todos"                # 计划就绪,进计划轴

解读:规划失败不阻塞执行,而是优雅降级——掉进 no_todos,与 planning_disabled 殊途同归,都去走 ReAct 循环。这是全文件第一处降级设计,后面还能见到同款思路。

3、双模式共存机制

两条轴共用一张图、一套状态、一组终点,共存靠三个机制。

机制一,入口分叉。上面 check_todos_available 的三分叉就是模式开关:有 todos 走计划轴,没 todos 走 ReAct 轴。计划轴的循环结构是"派发-执行-观察"三段:has_todos 进 get_ready_todos_method,按依赖找就绪步骤并四路分流——无就绪且全部完成走 all_todos_complete;无就绪但没完成是依赖死锁,记下原因走 needs_replan;一个就绪走 single_todo_ready 串行;多个就绪走 multiple_todos_ready 并行。

计划轴的执行不在主对话里做。execute_todo_sequential 调 _ensure_step_executor 拿 StepExecutor,配一个只含依赖最终结果的 StepExecutionContext——源码注释写得很清楚:只传依赖步骤的 final results,绝不传执行轨迹、工具调用或消息历史——再按 max_step_iterations(默认 15)与 step_timeout 隔离执行单步。步内自治,步外只看结果,这是计划轴与 ReAct 轴最根本的差别:前者把循环拆给每一步自带,后者在共享 messages 上滚动。执行完也不标完成,路由到 step_executed 交给观察轴打分(第 3 篇 planning config 里的 reasoning_effort 参数在这里生效)。三档处置各有分寸:低档最省,观察打分后成功即继续,只有硬失败才触发重规划;中档失败时看观察员意见,明确要求重规划才 replan,否则标记失败后继续;高档是完整决策管线,除了继续与重规划,还有微调待办描述(refine_and_continue)与"目标已提前达成"的提前收官(goal_achieved)两条额外通道,自适应最强、延迟也最高。多步就绪时还有并行通道:execute_todos_parallel 把各就绪步骤丢进线程池并发执行,结果再逐个补观察,回到派发循环。

机制二,iterations 只属于 ReAct 轴,且只在三个位置递增:increment_and_continue(工具没满足当前步)、recover_from_parser_error(解析失败)、recover_from_context_length(上下文超限)。每递增一次回到 initialized 标签,经 continue_iteration 桥接进 check_max_iterations 闸门,再入下一轮。计划轴全程几乎不动 iterations,但字段始终在场——两条轴随时可能互换跑道。

机制三,AgentFinish 劫持。ReAct 循环里模型给出最终答案本该收官,但 todos 还有活时,_route_finish_with_todos 会改写终点:

def _route_finish_with_todos(self, default_route):
    if self.state.todos.items and not self.state.todos.is_complete:
        if self.state.todos.current_todo:
            return "todo_satisfied"    # 有待办:答案算完成当前步
    return default_route               # 无待办:正常收官

解读:这就是双模式的交汇点。同一个"最终答案",todos 为空时是终点(agent_finished),todos 有值时是"当前步满足"(todo_satisfied)——后者经 mark_todo_complete 把结果写回 todo、追加一条 SYSTEM 消息进历史,再回 has_todos 派发下一步。一次 kickoff 里,两轴可以交替接管。另有一条 legacy 注入路径(todo_injected 标签):把步骤上下文注入共享消息再走 ReAct 循环,planning 开启时新路径优先,一般不经过,属新旧切换期的兼容残留。

4、工具调用循环

ReAct 轴的心脏是"决策-执行-回填"三拍。第一拍,call_llm_and_parse:

@router("continue_reasoning")
def call_llm_and_parse(self):
    ...
    enforce_rpm_limit(self.request_within_rpm_limit)
    answer = get_llm_response(
        llm=self.llm,
        messages=list(self.state.messages),
        callbacks=self.callbacks,
        printer=PRINTER,
        response_model=effective_response_model,
        executor_context=self,
    )
    formatted_answer = process_llm_response(answer, self.use_stop_words)
    self.state.current_answer = formatted_answer
    return "parsed"
    # 异常分支:OutputParserError → "parser_error"
    # 上下文超限 → "context_error",其余直接上抛

解读:解析产物只有两种——AgentAction(要调工具)或 AgentFinish(给答案),由 parser.py 完成。两个异常分支各自路由到恢复方法,把 iterations 加一后回 initialized 重来;其中 context_error 分支交给 handle_context_length 消化超限——第 7 篇预告的"上下文逼近上限做摘要",入口就在这条分支。structured output 有个细节:effective_response_model 只在没有 original_tools 时才带上,带工具的请求不挂 schema,答案的自由文本留给第 7 节的收尾阶段再结构化。

第二拍,parsed 之后 route_by_answer_type 按 Action 或 Finish 分流,Action 走 execute_tool_action:

@router("execute_tool")
def execute_tool_action(self):
    action = cast(AgentAction, self.state.current_answer)
    tool_result = execute_tool_and_check_finality(
        agent_action=action,          # 委派:真正执行在工具层一侧
        tools=self.tools,
        tools_handler=self.tools_handler,
        task=self.task,
        agent=self.agent,
        crew=self.crew,
    )
    tool_result.result += check_repeated_tool_call(
        self._tool_call_counts,       # 五连熔断在此挂载
        tool_name=action.tool,
        tool_args=action.tool_input,
        result=tool_result.raw_result,
    )
    result = self._handle_agent_action(action, tool_result)
    self.state.current_answer = result
    ...
    return "tool_completed"           # 观察已回填消息列表

解读:执行器自己不碰工具——execute_tool_and_check_finality 把 Action 委派给 tools/ 目录的工具执行层(ToolUsage、ToolsHandler、缓存都住在那边),拿回结果后由 _handle_agent_action 把含 Observation 的结果文本追加进 messages,再补一条 post_tool_reasoning 提示词的 user 消息,督促模型基于观察推理下一步。若工具带 result_as_answer=True,结果直接折算成 AgentFinish,is_finished 置位,走 tool_result_is_final 提前收官。异常分支同样优雅:报错拼成 error observation 回填,模型有机会自救;只有 HookAborted 与 ToolExecutionFailedError 这类"故意停"才直接上抛。

第三拍,tool_completed 之后 check_todo_completion 判定本轮成果归属:todos 为空返回 todo_not_satisfied,increment_and_continue 把 iterations 加一回到闸门,循环就此闭合。判定规则本身值得一读——Action 用了预期工具(todo 未指定工具则任意工具都算)即满足,Finish 一律满足,这正是两轴在同一循环里咬合的齿。原生工具是平行的一套:闸门处按 use_native_tools 分流到 continue_reasoning_native,call_llm_native_tools 携带 OpenAI schema 调 LLM,工具调用批量存进 pending_tool_calls,execute_native_tool 逐个执行并把结果以 tool 角色消息回填;这条路径上 todo 的判定更宽松,源码注释明说"任何工具执行都算满足当前 todo"。一旦提供商不支持原生调用,_downgrade_to_text_tool_calling 当场降级回文本路径,连降级提示词都替模型补好了。

5、三道闸与五连熔断

轮次闸门集中在一个方法里:

@router(or_(initialize_reasoning, continue_iteration))
def check_max_iterations(self):
    if has_reached_max_iterations(
        self.state.iterations, self.max_iter
    ) or repeated_tool_call_limit_reached(self._tool_call_counts):
        return "force_final_answer"     # 闸门落下:强制收答案
    if self.state.use_native_tools:
        return "continue_reasoning_native"
    return "continue_reasoning"

解读:闸门同时挂在 initialize_reasoning 与 continue_iteration 两个方法上,任何一轮进入推理前先过检。三道闸的参数与行为对比如下:

闸门 默认值 触发条件 触发后动作
max_iter 25 iterations 达到上限 强制 LLM 给最终答案后收官
max_method_calls 250 单个方法调用次数超限 Flow 运行时直接抛错
五连熔断 5 次 同名同参同结果连续调用 先警告后按工具失败处理

三道闸各管一层。max_iter 管 ReAct 轮次,超限走 force_final_answer,ensure_force_final_answer 用 handle_max_iterations_exceeded 拿现有对话硬要一个收尾答案——宁可强求,不空手抛错。max_method_calls 管 Flow 图本身:一轮要穿过七八个 router 方法,方法调用配额因此放大十倍,_setup_executor 里算出 max_iter×10;Flow 运行时默认只给 100,执行器显式抬到 250,执行点在 runtime 里,超限抛 "Method has been called N times"。五连熔断管原地打转:第 2 篇从用户视角见过"再调也不会变,用现有结果作答"的警告与第 5 次的强制失败,现在位置清楚了——check_repeated_tool_call 在 execute_tool_action 里随每次调用执行,判定键是工具名、参数、结果三者哈希,第 4 次警告、第 5 次按 REPEATED_CALL 走工具失败策略,同时 repeated_tool_call_limit_reached 在闸门处兜底强制收官。计划轴另有配套小闸:max_replans 默认 3 次防重规划风暴,max_step_iterations 默认 15 次给每步自治预算。

6、replan 动态重规划

计划不是一次定终身,触发源有三类:观察轴判定步骤硬失败且 needs_full_replan(medium 与 high 档都可能);check_more_todos 与 after_parallel_execution 里的 _should_replan 巡检——累计两个失败步、两个错误步,或最后一条消息出现 "replan"、"try a different approach" 这类指示词;以及 get_ready_todos_method 撞上依赖死锁。三类最终汇到 _trigger_replan:先 _build_replan_context 攒出"已完成什么、败在哪、这是第几次重规划"的上下文,拼进任务描述(临时替换 task.description,finally 里还原),重跑一遍 AgentReasoning,再 replace_pending_todos 只替换待办步骤、保留已完成历史。重规划本身失败也不砸场子:保留现有 todos 继续跑。replan_count 到 3 次即封顶,拿现有结果收官。

7、finish 收尾与结果组装

四个终点标签——all_todos_complete、agent_finished、tool_result_is_final、native_finished——全部汇入 finalize:

@listen(or_("all_todos_complete", "agent_finished",
            "tool_result_is_final", "native_finished"))
def finalize(self):
    with self._finalize_lock:           # 并发分支只放一个进来
        if self._finalize_called:
            return "completed"
        self._finalize_called = True
    if self.state.current_answer is None:
        todos_with_results = [t for t in self.state.todos.items if t.result]
        if todos_with_results:
            ...                         # 末步直通或 LLM 合成
    ...
    self.state.is_finished = True
    return "completed"

解读:finalize 是幂等的。同一标签可能被多个方法发出、并行分支可能同时到达终点,_finalize_lock 加 _finalize_called 保证只组装一次。结果组装是三级兜底:ReAct 路径 current_answer 已有值,直接用;计划路径若末步结果够像答案——无 response_model、无指定工具、非报错、超过 200 字符或 30 个词且带句读——就末步直通,否则 _synthesize_final_answer_from_todos 发一次合成 LLM 调用把各步结果揉成连贯答案,这也是计划路径唯一应用 response_model 的位置;合成失败退化为拼接,再不行兜底一句"执行完成但没有产出"。出 finalize 后回到 invoke:断言拿到 AgentFinish 否则 RuntimeError,ask_for_human_input 为真则进入人工反馈循环(反馈轮会置 _is_feedback_iteration,下一轮 generate_plan 直接跳过),最后 _save_to_memory 落记忆,返回 {"output": ...}。

8、总结

本文把执行引擎拆到了齿轮级:AgentExecutor 以 1 个 @start、28 个 @router、3 个 @listen 织成一张双轴循环图;generate_plan 用 AgentReasoning 造计划、折 todos,失败则降级 ReAct;计划轴 StepExecutor 隔离执行、观察轴按 reasoning_effort 分档处置;ReAct 轴靠 iterations 计数滚动,工具结果以 Observation 回填;_route_finish_with_todos 让两轴随时互换跑道;max_iter 25、max_method_calls 250、五连熔断三道闸分层兜底;replan 带上下文重跑规划、只换待办;finalize 幂等收口、三级组装答案。第 3 篇的 planning=True、第 2 篇的熔断现象,至此全部对上了实现。

三个练习留给读者:

  • 把 28 个 @router 标签抄成状态迁移表,与本文架构图互相验证
  • 构造 depends_on 指向不存在步骤号的计划,观察死锁触发的 replan
  • 把 max_iter 调成 3 跑一个必调工具的任务,数强制收答案前的轮次

源码篇收官在第 9 篇:Flow 内核——本篇当作黑盒用的 Flow 基类,它脚下的 runtime、持久化与事件系统,下一篇拆开看。对于读完仍觉得循环图复杂的读者,建议回第 4 篇把事件驱动机制再过一遍:执行引擎不过是 Flow 的一次重度自举,理解了 Flow,齿轮自然就顺了。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

759
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

441
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

415