CrewAI 从零上手：用 JSON 配置搭出多智能体工作流
CrewAI（github.com/crewAIInc/crewAI）是 crewAIInc 出品的开源 Python 多智能体编排框架（把多个各有分工的 AI 角色组织起来协同干活的框架）。截至 2026-08-26 的 GitHub 主页快照：57.6k star、8.2k fork，GitHub「Used by」显示约 1.9 万个仓库引用，326 名贡献者；最新版本 1.15.17 于 2026 年 8 月 20 日发布。它面向「比单个 prompt 更复杂」的多步任务：几个角色分工的 Agent 协作完成任务，或用事件驱动的 Flow 精确控制每一步。核心结论：uv tool install crewai 装 CLI，crewai create crew 生成 JSON 配置项目，改两个 .jsonc 后 crewai run 即可跑通第一个多智能体工作流；步骤固定的自动化再按需升级到 Flow。
它解决什么问题
单个 prompt 适合一问一答，但真实任务往往是多步骤的：先查资料、再整理、再写报告；过程中还要调用搜索工具、输出结构化结果。CrewAI 把这类任务拆成两个原语来处理：
- Crews（团队）：一组有角色、目标、工具的 Agent 自主协作。适合需要灵活决策、动态分工的任务。
- Flows（流程）：事件驱动的执行流水线，用
@start、@listen、@router装饰器精确控制每一步做什么，支持条件分支与状态管理。适合步骤固定、需要确定性控制的自动化。大白话理解：@listen相当于「第 2 步等第 1 步完成后自动接力」，@router相当于「如果超时就改走方案 B」。
两者可以组合：Flow 里嵌 Crew，既保留 Agent 的自主性，又在外层拿到确定性控制。
安装与项目脚手架
环境要求是 Python >= 3.10 且 < 3.14，依赖管理推荐用 uv。安装 CrewAI CLI 只需一条命令：
uv tool install crewai
生成一个新项目用脚手架命令，默认产出 JSON-first 结构：
crewai create crew my_project
项目目录如下：
my_project/
├── .gitignore
├── .env
├── agents/ # 每个 Agent 一个 jsonc，定义角色/目标/背景/LLM/工具
├── crew.jsonc # 任务、流程类型、输入默认值
├── knowledge/ # 可选知识库文件
├── skills/ # 可选技能文件
├── tools/ # 可选自定义工具
├── pyproject.toml
└── README.md
Agents 定义在 agents/*.jsonc，任务与团队设置集中在 crew.jsonc，运行时代码只需 crewai run 直接加载这些 JSON。
如果习惯旧的 Python/YAML 写法，可用 --classic 参数生成 crew.py 加 config/agents.yaml、config/tasks.yaml 的经典结构。
用 JSON 配置搭一个研究小组
以官方示例「latest-ai-development」为例：一个研究员负责调研最新 AI 进展，一个分析师把结果整理成报告。先生成项目：
crewai create crew latest-ai-development
cd latest_ai_development
agents/researcher.jsonc——定义研究员角色：
{
"role": "Senior Data Researcher on {topic}",
"goal": "Uncover cutting-edge developments in {topic}",
"backstory": "You're a seasoned researcher who finds relevant information and presents it clearly.",
"llm": "openai/gpt-4o",
"tools": ["SerperDevTool"],
"settings": { "verbose": true }
}
agents/reporting_analyst.jsonc——定义分析师角色：
{
"role": "Reporting Analyst on {topic}",
"goal": "Create detailed reports based on {topic} data analysis and research findings",
"backstory": "You're a meticulous analyst who turns complex data into clear, concise reports.",
"llm": "openai/gpt-4o",
"settings": { "verbose": true }
}
crew.jsonc——把两个 Agent 和两个任务串起来：
{
"name": "Latest AI Development",
"agents": ["researcher", "reporting_analyst"],
"tasks": [
{
"name": "research_task",
"description": "Conduct thorough research about {topic}. Find recent, relevant information.",
"expected_output": "A list with 10 bullet points of the most relevant information about {topic}.",
"agent": "researcher"
},
{
"name": "reporting_task",
"description": "Review the research and expand each topic into a full section for a report.",
"expected_output": "A markdown report with the main topics, each with a full section of information.",
"agent": "reporting_analyst",
"context": ["research_task"],
"output_file": "output/report.md"
}
],
"process": "sequential",
"verbose": true,
"inputs": { "topic": "AI Agents" }
}
这里的 {topic} 是占位符，运行时可被替换。.env 里放模型提供商的 API key——agent 里的 llm 字段就指向这里配置的模型；要用网页搜索就再加 SERPER_API_KEY。CrewAI 不锁定模型厂商：默认走 OpenAI API，也支持通过 Ollama、LM Studio 接本地模型，以及各类自定义 LLM。
接着安装依赖并运行：
crewai install
crewai run
默认是 sequential（顺序）流程：前一个任务产出传给后一个任务。换成 hierarchical（层级）流程，框架会自动安排一个经理 Agent 来分包、协调与验收。最终报告会写到 output/report.md。
步骤固定时，改用 Flow 接管控制
上面的 Crew 让 Agent 自主发挥，适合研究、写作这类任务。当自动化流程带有固定的业务逻辑时，用 Flow 把步骤钉死：@start 声明流程入口，@listen 在某个步骤完成后触发下一步，@router 按结果分派到不同分支，并可用 or_、and_ 组合多个触发条件。Flow 内部可以直接调用 Crew 并传入结构化状态，让 Agent 团队成为大流程中的一环，数据操作与分支判断仍由 Python 代码接管。
适用场景
README 的定位很直接：当你需要的不只是单个 prompt 或聊天机器人时，再上 CrewAI——多步工作流、多角色分工、工具调用、结构化输出、人工审核、把自主推理与明确的业务逻辑结合。据官方课程站 learn.crewai.com 自述，社区课程已培养 10 万余名认证开发者。
整个上手流程就是「装 CLI、生成项目、改两个 jsonc 文件、run」四步。Crews 面向自主协作，Flows 面向精确控制，两者同属一套 Python API 与 JSON 配置，从原型验证到生产级流程无需更换框架。