CrewAI 1.15 拆解:角色化多智能体与Flows确定性编排

一句话结论：CrewAI 是目前最像"组建一支 AI 团队"的框架——你定义角色、目标、背景故事，它自动分工协作。但它真正的杀手锏不是角色扮演，而是 1.x 之后重构的双层架构：Crews 管智能，Flows 管控制。做原型最快，做生产得靠 Flows。 

一、双层架构：Crews 和 Flows 各管什么

CrewAI 的核心不是"多智能体"，而是把自主性和确定性分开放在两层：

官方的建议很直接：生产环境从 Flow 开始，在某个 Flow 步骤里塞进 Crew。完整链路是 Flow 触发 → 管理状态 → 把复杂任务交给 Crew → Agent 协作产出 → 结果回到 Flow → Flow 继续往下走。

这个设计恰好回应了多智能体框架最常见的两个坑：纯自主的 Agent 在 demo 里很惊艳、在管道里不可预测；纯工作流可控但呆板。Flows 让"判断"只出现在需要判断的节点上。

二、2026 年最大的变化：项目变成 JSON-first

如果你以前用过 CrewAI，会发现新版脚手架结构变了。crewai create crew 现在生成的是纯 JSON 配置，不再强制 crew.py + 两个 YAML：

research_crew/ ├── .gitignore ├── .env ├── agents/ │   └── researcher.jsonc ├── crew.jsonc ├── knowledge/ ├── pyproject.toml ├── skills/ └── tools/

老用户想保留 YAML 布局，加 --classic 就行。

一个 Agent 的定义长这样——注意它就是一组"人设 + 行为配置"，没有代码：

{   "role": "Senior Research Specialist for {topic}",   "goal": "Find comprehensive and accurate information about {topic}...",   "backstory": "You are an experienced research specialist...",   "llm": "provider/model-id",   "tools": ["SerperDevTool"],   "settings": {     "verbose": true,     "allow_delegation": false   } }

Crew 和任务定义在 crew.jsonc，context 字段指定任务间的依赖，inputs 给占位符提供默认值（缺了 run 会交互式追问）：

{   "name": "Research Crew",   "agents": ["researcher", "analyst"],   "tasks": [     {       "name": "research_task",       "description": "Conduct thorough research on {topic}...",       "expected_output": "A comprehensive research document...",       "agent": "researcher"     },     {       "name": "analysis_task",       "agent": "analyst",       "context": ["research_task"],       "output_file": "output/report.md",       "markdown": true     }   ],   "process": "sequential",   "memory": true,   "inputs": { "topic": "Artificial Intelligence in Healthcare" } }

process 两种取值：sequential（顺序执行）和 hierarchical（层级模式，需要指定 manager_llm 或 manager_agent，由管理者自动派活）。

三、Flows：装饰器把流程写成代码

Flow 侧仍然是 Python，用三个装饰器建立关系：@start() 定义入口，@listen(步骤) 监听上游完成，@router() 做条件分支。状态用 Pydantic 模型定义，类型安全：

from crewai.flow.flow import Flow, listen, start  class GuideCreatorState(BaseModel):     topic: str = ""     guide_outline: GuideOutline = None     sections_content: Dict[str, str] = {}  class GuideCreatorFlow(Flow[GuideCreatorState]):      @start()     def get_user_input(self):         self.state.topic = input("主题？")         return self.state      @listen(get_user_input)     def create_outline(self, state):         # 简单结构化输出直接调 LLM，不必绕一圈 crew         llm = LLM(model="openai/gpt-4o-mini",                   response_format=GuideOutline)         self.state.guide_outline = GuideOutline(             **json.loads(llm.call(messages=[...])))         return self.state.guide_outline      @listen(create_outline)     def write_sections(self, outline):         for section in outline.sections:             # 复杂的、需要协作的部分才交给 Crew             kickoff_content_crew(inputs={                 "section_title": section.title, ... })

这里有个很值得注意的细节：简单结构化输出直接调 LLM，只有真正需要多角色协作的环节才开 Crew。这是控制 Token 成本的关键——多智能体的开销往往是单智能体的数倍，把 Crew 当默认解是常见误用。复杂并行用 and_() / or_() 组合。

四、记忆系统被彻底重写了

这是 1.x 最容易被旧文档误导的地方。CrewAI 现在用单一的 Memory 类替代了原来的短期/长期/实体/外部四种记忆类型，核心变化是用 LLM 在写入时自动推断作用域、分类和重要性，召回时用"语义相似度 + 时间新鲜度 + 重要性"的复合打分排序。

from crewai import Memory  memory = Memory() memory.remember("我们决定用 PostgreSQL 做用户库。")  matches = memory.recall("数据库怎么定的？") for m in matches:     print(f"[{m.score:.2f}] {m.record.content}")  # 调权重（默认偏重语义，迭代快的项目要调高新鲜度） memory = Memory(recency_weight=0.5, recency_half_life_days=7)

作用域树是这套设计里最实用的部分。不指定作用域时，LLM 会分析内容并自己挂到树上合适的位置，作用域树随内容自然生长，不用预先设计 schema：

# 研究员有私有作用域，只能看到自己的 researcher = Agent(..., memory=memory.scope("/agent/researcher"))  # 写作者用团队共享记忆（不设 agent 级 memory） writer = Agent(role="Writer", goal="...", backstory="...")  print(memory.tree())# 看作用域层级和记录数

其他几个值得注意的实现细节：

• 默认存储 LanceDB
  ，落在 ./.crewai/memory，可用环境变量 CREWAI_STORAGE_DIR 改路径，也可实现 StorageBackend 协议换后端。
• 默认 embedder 是 OpenAI text-embedding-3-large
  ，分析用 LLM 默认 gpt-4o-mini。要完全离线就把两个都换成 Ollama。
• LLM 懒加载
  ：Memory() 构造时不会因为缺 API key 报错，只在实际调用时才暴露问题。
• remember_many() 是非阻塞的
  ，后台线程写；recall() 会自动等写完。批内余弦相似度 ≥ 0.98 的重复项直接丢弃，不花 LLM 调用。
• 每条记忆可带 source 和 private 标记
  ——私有记忆只有 source 匹配时才召回，多用户/企业场景做隔离就靠这个。

五、MCP 接入：字段级 DSL，最简洁的一种

现在给 Agent 接 MCP 工具，只要在 mcps 字段里写字符串，工具自动发现、自动挂载：

from crewai import Agent  agent = Agent(     role="Research Analyst",     goal="Research and analyze information",     backstory="Expert researcher with access to external tools",     mcps=[         "https://mcp.exa.ai/mcp?api_key=your_key",   # 整个服务器         "https://api.weather.com/mcp#get_forecast",    # 只取某个工具         "snowflake",                                  # 目录里已连接的 MCP         "stripe#list_invoices",                       # 指定工具     ] )

需要控制传输方式和工具过滤时，用结构化配置（MCPServerStdio / MCPServerHTTP / MCPServerSSE），三种格式可以在同一个列表里混用。要手动管连接生命周期才用 MCPServerAdapter，记得 stop()。

依赖：DSL 用 uv add mcp，Adapter 用 crewai-tools[mcp]。注意目前只支持 MCP 的 tools，不支持 prompts 和 resources，且只取返回内容里的第一个 text 块。

六、工具和自建工具

crewai-tools 内置工具按类别分：文件管理（FileReadTool、FileWriteTool）、网页抓取（ScrapeWebsiteTool、SeleniumScrapingTool）、关系库（PGSearchTool、MySQLSearchTool）、向量库（MongoDBVectorSearchTool、QdrantVectorSearchTool、WeaviateVectorSearchTool）、搜索（SerperApiTool、EXASearchTool）、多模态（DallETool、VisionTool）。

自建工具有两条路，装饰器更轻，继承类更可控：

# 轻量：装饰器 from crewai import tool  @tool("查询护理质控报表") def query_nqc_report(period: str) -> str:     """按时间段查询质控统计报表"""     return run_sql(period)  # 需要控制 schema 和描述时：继承 BaseTool from crewai.tools import BaseTool  class NqcQueryTool(BaseTool):     name: str = "NQC 报表查询"     description: str = "查询指定时间段的护理质控统计报表"     def _run(self, period: str) -> str:         return run_sql(period)

工具描述就是给模型看的 prompt，写得含糊，模型就会瞎传参数——这比框架本身的坑更常见。

七、生态侧：Crew Studio 和 AMP

开源框架之外，CrewAI 在往平台侧走，几块东西值得知道：

• Crew Studio
  ——用自然语言描述工作流，它自动生成架构和代码。三种节点类型：单Agent 节点、Crew 节点（把整支多智能体团队塞进一个步骤）、Router 节点（条件分支）。已接 1000+ 应用连接器。生成的代码可导出为 Python。
• Control Plane
  ——在执行路径上做治理：每次 LLM 调用和工具调用的实时追踪与成本核算、RBAC 与不可篡改审计日志、执行中的人工审批闸门、运行时钩子（PII脱敏、策略检查注入到每个调用点）。
• AMP（SaaS）
  零安装、托管扩缩容；Factory（自托管）容器化交付，支持任意云和本地部署。
• 编码 Agent 技能包
  ：npx skills add crewaiinc/skills，让 Claude Code / Codex 这类工具按官方规范写 CrewAI 代码。

八、选型判断：什么时候该用，什么时候别用

适合CrewAI：

• 任务能拆成 2–5 个专业角色，交接顺序清晰——调研、分析、写作、审查这类流水线
• 小团队快速做原型，或者业务方想自己定义流程、不等工程师排期
• 需要现成的治理能力：审计、追踪、人工审批这些自己搭很累

不建议用：

• 复杂条件分支、需要暂停恢复的长流程——LangGraph 的显式图模型表达得更干净
• 高并发、低延迟的 Agent 服务——角色间通信开销是实打实的成本
• 成本敏感的批量任务——先用最简方案跑通，需求明确后再迁

更现实的判断依据是：框架选择往往不是"离生产最近"的那道瓶颈。真正难的是工具描述写不准导致模型瞎传参数、缺评估集导致改 prompt 后不知道是好了还是坏了、重试路径没加固导致一次 API 抖动就崩掉整个流程。先用你团队已经熟的那个框架跑通，需求清晰了再谈迁移。

九、可核验的参数

本文信息来自 CrewAI 官方文档（docs.crewai.com）与 PyPI 元数据，版本号与参数截至 2026 年 10 月。框架迭代快，抄代码前建议对一遍官方文档。