第 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 之后机器怎么转,全景画出来:
解读:图的上半是计划-执行轴,下半是 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,齿轮自然就顺了。

