CrewAI 源码:monorepo 拆包解读

QuibblerAgentQuibblerAgent 2026-11-18 约 30 分钟 16 次阅读

第 6 篇结尾预告过:源码篇要进 CrewAI 内部,去找那些"报错不露根因"现象的发生位置与包装层级。前六篇把 Crew、Flow、工具、记忆、层级流程的用法过了一遍,用法层面的疑问基本清零,剩下的疑问都有一个共同形状——文档说它"会自动完成",但没说在哪完成、谁完成、失败了怎么包装。这类问题只有源码能回答。

本篇是《CrewAI 由浅入深》第 7 篇、源码篇开篇:不追某个具体函数的细节,先把仓库的拆包格局与主包骨架摸清,建立一张"哪个功能住在哪个包、哪层目录"的地图,后面两篇深潜执行引擎与 Flow 内核时按图索骥。全文按"动机与姿势 → 六包全景 → 主包走读 → 核心类关系 → 执行循环骨架 → LLM 工厂路由 → 演进痕迹 → 总结"展开,版本口径同前六篇:PyPI 上的 CrewAI v1.15.41,2026 年 11 月,全部引用解包自该版 wheel。


1、为什么读 CrewAI 源码

读框架源码的动机通常三类,CrewAI 恰好各占一个硬例子。

第一类,调试黑盒。第 6 篇讲过层级流程"报错不露根因":异常被层层包装,用户看到的常是一句笼统的"任务失败"。翻开 agents/agent_executor.py 就能看到包装发生的位置——工具失败先折算成 ToolFailure,再按策略决定是提示模型重试还是抛出,栈回溯里那几层模糊消息全是这里的翻译层。知道位置,才记得住那条纪律:翻到最底部的原始异常再下判断。

第二类,二次开发。扩展点都藏在源码的接缝处:Agent 有 executor_class 字段可以整体换执行器;记忆存储认 StorageBackend 协议不认具体类;工具失败返回 ToolFailure 对象而非裸异常。这些接缝文档只点到名字,参数怎么传、何时构造,源码是最快的查法。

第三类,学框架设计。CrewAI 是少见的"拿自己造自己"的样本:执行引擎 AgentExecutor 直接继承 Flow——用第 4 篇学的事件驱动框架来实现 ReAct 循环。看懂这个自举,比读十篇架构文章更直观。

读的姿势也交代一下:不必 clone 仓库,解包 wheel 即可。wheel 里的源码与装进环境的包逐字节一致,离线可读、可 grep、可对照运行调试。命令如下:

pip download crewai==1.15.41 --no-deps -d wheels
python -m zipfile -e wheels/crewai-1.15.41-py3-none-any.whl src

解读:解包出的 src/crewai/ 就是本篇全部引用的出处。加 --no-deps 是为了先只拿主包——它牵出的兄弟包,下一节单独说。锁定版本号读还有一层好处:网上教程与本地代码对不上号时,你手里这份就是运行时的真相,连行号都能对上。

2、monorepo 六包全景

GitHub 仓库不是一个大包,而是 lib/ 目录下的 monorepo,六个子包各占一个目录。全部成员与依赖方向画出来:

flowchart LR subgraph lib[仓库 lib 目录] M[crewai 主包] C[crewai-core 基础设施] K[cli 命令行] T[crewai-tools] F[crewai-files] D[devtools] end U([用户代码]) --> M M --> C M --> K M -.->|装 extras 时| T

解读这张图的关键在箭头:用户代码只面对 crewai 主包,其余五包都被主包挡在身后——crewai-core 与 cli 是主包的固定依赖,版本号用 == 锁死在 1.15.41;crewai-tools 要装 crewai[tools] 才进来;crewai-files 与 devtools 不进用户环境。六包职责整理如下:

目录 PyPI 包 职责
crewai crewai 领域主体:Agent、Crew、Task、Flow、记忆
crewai-core crewai-core 基础设施:认证、遥测、平台 API、打印
cli crewai-cli 命令行:create、run、replay、test
crewai-tools crewai-tools 内置工具:搜索、抓取、文件读写
crewai-files 不独立发布 脚手架模板与项目文件(定性)
devtools 不发布 仓库内部开发工具链(定性)

最容易踩的认知陷阱是 crewai-core 的命名:它不是领域核心,是平台基础设施。解包这个包能看到全部家当——auth、telemetry、plus_api、token_manager、printer 这些模块,没有一个与 Agent 或任务执行有关;真正的领域核心(Agent、Crew、执行器)全部住在 crewai 主包里。依赖方向也是单向的:主包 import crewai_core 的打印与遥测,crewai_core 对主包一无所知——基础设施在下、领域在上,分层干净。

CLI 的拆包是另一处值得注意的痕迹:主包里的 crewai/cli/ 只剩一个垫片文件,把旧路径 crewai.cli.X 的导入重定向到独立包 crewai_cli 并弹弃用警告。crewai 命令本身(create、run、replay 这些第 6 篇用过的)全部住在 crewai-cli 包里。

3、crewai 主包结构走读

主包根目录下有 26 个子目录加十余个单文件,核心部分摘出来:

crewai/
├── __init__.py        # 入口:导出 Agent、Crew、Task、LLM 等
├── crew.py            # Crew 类定义与 kickoff
├── task.py            # Task 类定义
├── llm.py             # LLM 类与 LiteLLM 兜底
├── process.py         # Process 枚举
├── agent/             # Agent 本体:core.py、planning_config.py
├── agents/            # 执行设施:agent_executor.py、step_executor.py
├── crews/             # Crew 外围:crew_output.py
├── tasks/             # Task 外围:task_output.py、两类 guardrail
├── tools/             # BaseTool 契约、tool_usage、缓存
├── llms/              # base_llm、providers、litellm_catalog
├── memory/            # unified_memory、storage 后端
├── flow/              # Flow 基类、runtime、persistence
├── mcp/               # MCPServerStdio 等接入
├── project/           # CrewBase 等脚手架装饰器
├── utilities/         # planner、llm_utils、agent_utils
└── translations/      # 多语言提示词模板

结构里藏着一条规律:单数文件放类本体,复数目录放外围设施。Crew 类在 crew.py,crews/ 里放的是 CrewOutput;Task 类在 task.py,tasks/ 里放 TaskOutput 与守卫。这条规律最典型的体现是 agent 与 agents 的分野——agent/core.py 定义 Agent 这个"人"(字段、人设、配置),agents/ 目录养着"执行机器":3654 行的 agent_executor、单步执行器、输出解析器、工具处理器。前者回答"是谁",后者回答"怎么干活"。

目录树里还有两处值得点名。flow/ 比第 4 篇用到的部分厚实得多:runtime、persistence、visualization、dsl 各占一席,执行持久化与断点恢复(第 4 篇提过的 persist and resume)就住在 persistence 里。utilities/ 则是公共后院——第 3 篇的规划器、本篇的 LLM 工厂与调用熔断全寄居于此,名字低调,住客个个要紧。

入口 __init__.py 的导出分两档,精简后如下:

from crewai.agent.core import Agent
from crewai.crew import Crew
from crewai.flow.flow import Flow
from crewai.llm import LLM
from crewai.task import Task
# ……另有十余个即时导入

_LAZY_IMPORTS = {
    "CrewBase": ("crewai.project", "CrewBase"),
    "Memory": ("crewai.memory.unified_memory", "Memory"),
}

def __getattr__(name):
    """重模块首次访问才导入(Memory 会拖出向量库)。"""
    ...

解读:高频名字(Agent、Crew、Task、LLM、Flow)import 即到位;Memory 这类依赖向量库的名字走模块级 __getattr__ 惰性导入——第 3 篇"不开记忆也不受 lancedb 拖累"的体验,机制就在这几行。__all__ 共 18 项,是官方承诺的稳定 API 面,第 7 节会回到这一点。

4、核心类关系与执行管线

Crew 聚合 Agent 与 Task,执行时经 Agent 落到 AgentExecutor。类关系画出来:

classDiagram class Crew { +agents: list +tasks: list +process: Process +kickoff(inputs) CrewOutput } class Agent { +role: str +llm: BaseLLM +executor_class: type +execute_task(task) Any } class Task { +description: str +agent: Agent +execute_sync() TaskOutput } class AgentExecutor { +max_iter: int +invoke(inputs) dict } Crew "1" o-- "*" Agent : 成员 Crew "1" o-- "*" Task : 任务清单 Task --> Agent : 指派 Agent --> AgentExecutor : 委托执行 AgentExecutor --> LLM : 推理调用 AgentExecutor --|> Flow : 继承

解读:聚合关系是"配置期"的——你在 Crew 构造参数里给的列表;执行期走 Task → Agent → AgentExecutor 这条委托链。注意最后一行:AgentExecutor 继承 Flow,执行器本身就是第 4 篇那个事件驱动框架的子类。

链条的第一环在 crew.py 的 kickoff。两种 Process 的分岔比想象中小得多,节选如下:

# crewai/crew.py 节选(有省略,下同)
def kickoff(self, inputs=None):
    if self.process == Process.sequential:
        result = self._run_sequential_process()
    elif self.process == Process.hierarchical:
        result = self._run_hierarchical_process()

def _run_sequential_process(self):
    return self._execute_tasks(self.tasks)

def _run_hierarchical_process(self):
    self._create_manager_agent()
    return self._execute_tasks(self.tasks)

def _create_manager_agent(self):
    manager = Agent(
        role=i18n.retrieve("hierarchical_manager_agent", "role"),
        goal=i18n.retrieve("hierarchical_manager_agent", "goal"),
        backstory=i18n.retrieve("hierarchical_manager_agent", "backstory"),
        tools=AgentTools(agents=self.agents).tools(),
        allow_delegation=True, llm=self.manager_llm,
    )
    self.manager_agent = manager

解读:两种 Process 最终汇入同一个 _execute_tasks,差别只在层级流程先多造一个经理 Agent。更值得看清的是经理的出身——role、goal、backstory 三件套来自 translations/ 里的多语言模板,工具是一组委派专用的 AgentTools(派活、问话都靠它们)。第 6 篇说经理"由框架自动组装",组装现场就在这十几行。顺着 _execute_tasks 往里,每个 Task 调 agent.execute_task(),再走一步就到执行器:

# crewai/agent/core.py 节选
def _execute_without_timeout(self, task_prompt, task):
    invoke_result = self.agent_executor.invoke(
        {
            "input": task_prompt,
            "tool_names": self.agent_executor.tools_names,
            "tools": self.agent_executor.tools_description,
            "ask_for_human_input": task.human_input,
        }
    )
    return invoke_result["output"]

解读:invoke 收到的 input 是拼装完的任务提示词——系统提示词、工具 schema、上下文、第 3 篇的记忆召回,全在上一层拼好;执行器只管"循环、调工具、出答案"。这正是分层的价值:提示词工程归 Agent,循环控制归执行器。

5、AgentExecutor 的 ReAct 循环

执行器全名 agents/agent_executor.py,3654 行,是主包里最大的单文件。配角也各有分工:parser.py 把模型输出解析成 AgentAction(要调工具)或 AgentFinish(给最终答案)两种结局,step_executor.py 管单步落地。主角的骨架精简后如下:

class AgentExecutorState(BaseModel):
    messages: list = []        # 对话历史
    iterations: int = 0        # ReAct 轮次
    plan: str | None = None    # 计划(计划-执行范式用)
    todos: TodoList            # 步骤清单
    replan_count: int = 0      # 重规划次数
    observations: dict = {}    # 每步观察结果

class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
    max_iter: int = 25
    max_method_calls: int = 250   # max_iter 的十倍

    @start()
    def generate_plan(self): ...
    # 规划开启则先生成计划并拆成 todos

    @router("step_executed")
    def observe_step(self): ...
    # 按观察置信度分流 low、medium、high 三档

解读三处。其一,执行引擎是 Flow 的子类:@start() 的 generate_plan 是入口,之后十多个 @router 按"step_executed""step_observed_low""has_todos""replan_now"这类标签流转——第 4 篇学的路由机制被框架自己拿来造了 ReAct 循环。invoke 里还有一处妙笔:检测到自己身处事件循环时自动返回协程,让 Flow 里的步骤能直接 await 一个 Agent。其二,状态模型同时容纳两套范式:iterations 服务 ReAct(想一步做一步),todos 与 replan_count 服务计划-执行(先列清单再逐项干),第 3 篇提过的 Agent 级 planning=True 打开的就是后者。其三,轮次有两道闸:max_iter 默认 25,方法调用上限 250。

循环的"停"除了轮次上限,还有第 2 篇讲过的熔断——连续 5 次相同工具调用即停。当时当行为特性讲,源码里它叫 check_repeated_tool_call,住在 utilities/agent_utils.py:

MAX_REPEATED_TOOL_CALLS = 5

def check_repeated_tool_call(counts, *, tool_name, tool_args, result, ...):
    key = hash(json.dumps([tool_name, tool_args, str(result)]))
    if key not in counts:
        counts.clear()          # 换了调用,连击清零
    counts[key] = streak = counts.get(key, 0) + 1

    if streak == MAX_REPEATED_TOOL_CALLS - 1:
        return "再调也不会变,用现有结果作答"  # 第 4 次:警告
    if streak == MAX_REPEATED_TOOL_CALLS:
        handle_tool_failure(
            ToolFailure(reason=ToolFailureReason.REPEATED_CALL))

解读:判定键是"工具名 + 参数 + 结果"三者哈希——三样全同才算连击,换一个参数就清零重数。第 4 次先给模型一句"再调也不会变"的劝告,第 5 次才按 REPEATED_CALL 走工具失败策略。这个设计比单纯数调用次数聪明在能分辨"重试"与"原地打转"。

6、LLM 抽象与工厂路由

llm.py 里的 LLM 类还有第二个身份:路由工厂。构造入口 __new__ 做四级分流,骨架如下:

class LLM(BaseLLM):
    def __new__(cls, model, is_litellm=False, **kwargs):
        """路由优先级:
        1. custom_openai=True,强制走原生 OpenAI 通道
        2. 显式给了 provider,就用它
        3. 模型名带斜杠且前缀命中原生五家
           (openai、anthropic、azure、bedrock、gemini)→ 原生 SDK
        4. 其余一律交给 LiteLLM
        """
        route = cls._resolve_route(model, kwargs)
        if route.native_class is not None and not is_litellm:
            return route.native_class(model=model, **kwargs)
        return super().__new__(cls)   # 回落 LiteLLM 通道

解读:CrewAI 没把多提供商支持全押给 LiteLLM,而是主流五家走原生 SDK、长尾交给 LiteLLM 兜底。原生实现在 llms/providers/ 下,anthropic、azure、bedrock、gemini、openai、openai_compatible、snowflake 各占一个目录;LiteLLM 通道还随身带一份 litellm_catalog/ 里的模型价格表,token 记账不必联网查。第 1 篇的 deepseek/deepseek-chat 走的就是第 3 级判定——前缀不在原生五家,落到 LiteLLM。

LLM 之外还有第二个工厂 create_llm(utilities/llm_utils.py),负责"从配置造实例":传 LLM 实例原样直通,传字符串包成 LLM(model=...),传字典展开成构造参数,传 None 走环境变量回退。Crew 的 manager_llm 能接受一个字符串就是它的功劳。两个工厂分工清楚:create_llm 管入口宽容,__new__ 管内部选路。

llms/ 目录里还住着两位管家:context_window.py 盯着上下文水位,逼近上限时把老消息摘要压缩;retry.py 管重试策略。这两位与执行引擎的关系比与本节更近,第 8 篇深潜时正面讲,这里先记下门牌。

7、演进痕迹与框架成熟度

源码里最耐读的不是代码,是变更留下的痕迹。三处痕迹拼出 CrewAI 的成熟度曲线。

第一处,v1.15.29 删掉了旧执行器 CrewAgentExecutor。现在的包里这个名字只剩"守卫":把它传给 executor_class 直接报错,错误消息写着"CrewAgentExecutor has been removed. Use crewai.agents.agent_executor.AgentExecutor";从 crewai.agents 包 import 这个名字同样触发 ImportError。一个动作连守两道门,说明官方清楚有人在子类化旧执行器,宁可硬拦也不让旧代码悄悄跑错。版本边界也有内部证据:summarize_messages 的弃用警告里明说"保留 pre-1.15.29 的参数顺序"——破坏性变更发生在哪个版本,源码自己盖了章,细节可对照 GitHub Releases。

第二处,CLI 拆包。第 2 节那个垫片文件是迁移的活化石:旧导入路径被拦截、重定向、警告三连,新代码全部住进 crewai-cli。

第三处,规划器的简化。第 3 篇按文档口径说 CrewPlanner"组装 PlannerCrew,用小 Crew 规划大 Crew";v1.15.41 源码里 PlannerCrew 这个类已经查无此人——utilities/planning_handler.py 的实现是造一个规划 Agent 加一个规划 Task,execute_sync() 直接执行,Crew 这层包装被省掉,默认规划模型写着 gpt-6-luna。文档与源码的时差本身就是一课:教程口径要拿源码对表,本系列亦然。三处痕迹的要点收拢如下:

痕迹 变更 对使用者的含义
v1.15.29 移除旧执行器 破坏性重构,双守卫拦截 子类化内部类要盯版本说明
CLI 拆包 主包留兼容垫片 旧导入能跑,新代码用 crewai_cli
PlannerCrew 消失 简化为 Agent 加 Task 直跑 文档口径可能滞后于源码

框架的成熟度不看加了多少功能,看敢删多少东西。

三处痕迹指向同一个判断:这是一个敢做减法的框架。删旧执行器、拆 CLI、简化规划器,都是在兼容包袱与内部整洁之间选了后者。代价也划得清楚——内部 API 不承诺稳定,承诺只给 __init__.py 那一列 __all__。写扩展时贴着 __all__ 与文档化协议(StorageBackend、BaseTool、ToolFailure)走,升级才不容易踩雷;对外 API 面足够窄,也解释了官方为什么敢把破坏性变更压在 1.15.x 的补丁号里发布。

8、总结

本文给源码篇立了地图:仓库是 lib/ 下六包 monorepo,用户只面对 crewai 主包;crewai-core 名为核心实为基础设施,CLI 已拆成 crewai-cli;主包"单数文件放类本体、复数目录放外围",agent 是人、agents 是执行机器;kickoff 之后 sequential 与 hierarchical 汇入同一条 _execute_tasks 管线,经理 Agent 由提示词模板现场组装;执行器 AgentExecutor 共 3654 行,继承 Flow 自举出 ReAct 循环,max_iter 25 与"三全同连击五次熔断"两道闸兜底;LLM 走 __new__ 四级路由,主流五家原生 SDK、长尾 LiteLLM 兜底;v1.15.29 的破坏性重构、CLI 拆包、PlannerCrew 简化,共同勾勒出一个敢做减法的成熟框架。

三个练习留给读者:

  • 按第 1 节命令解包 wheel,数一数 __all__ 的 18 项,再找出三个常用却不在其中的类
  • 在 _create_manager_agent 加 print 跑一次层级流程,打印经理三件套模板原文
  • 把 LLM 工厂的四级路由抄成决策表,预测五个模型字符串各走哪条通道,再验证类型

源码篇下一站是第 8 篇:执行引擎深潜——@start 与十多个 router 标签如何串成完整的 ReAct 加计划-执行循环,todos 与 replan 怎样协作,上下文窗口逼近时由谁来做摘要。对于想真正吃透 CrewAI 的工程师,建议先把本篇的地图跑熟:解包、grep、定位,三个动作练成肌肉记忆,后面两篇读起来就是顺着地图散步。

相关推荐

​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