直接结论

CrewAI 是围绕 Agent、Task、Crew、Process 与 Flow 组织的 Agent 编排框架。当前文档区分两个实用层级:

  • Crew 是一项协作式模型工作的执行单元;
  • Flow 负责一个或多个 Crew 周围的应用状态和显式控制。

新建独立 Crew 的当前文档采用 JSON-first 结构,即 crew.jsonc 与 agents/*.jsonc;Classic Python/YAML 结构仍受支持。生产环境则建议 Flow-first,让状态转移、分支、持久化和恢复清晰可见。

框架不能证明多 Agent 比单 Agent 更好。先建立最小基线,只有角色分工创造了可测量价值时才增加 Crew。

选择正确抽象

需求 最简单的有效抽象
确定性转换 普通代码
一次有界模型判断 一个带类型结果的模型调用
一个带工具的 Agent Agent
按角色拆分的协作任务 Crew
状态、分支、等待、恢复与多个 Crew Flow
持久业务副作用 带鉴权和幂等的应用服务

Role 或 Backstory 会影响模型行为,但不能强制能力边界。Tool List 能限制 Agent 可提议的工具,但工具服务仍必须认证调用者、校验租户和对象、验证参数并控制副作用。

当前项目路径

JSON-first 独立 Crew

当前 Build Your First Crew 文档给出如下结构:

text
research_crew/
├── crew.jsonc
├── agents/
│   ├── researcher.jsonc
│   └── analyst.jsonc
├── tools/
├── knowledge/
├── skills/
├── pyproject.toml
└── uv.lock

使用项目已固定的 CLI 版本创建并运行:

bash
crewai create crew research_crew
cd research_crew
crewai install
crewai run

不要把未固定版本的教程直接复制进生产。记录 CrewAI Package 与 CLI 版本、锁定依赖,并让生成配置进入代码审查。

Classic Python/YAML Crew

需要 JSON-first 表面无法表达的 Python 定制时,仍可使用 Classic 路径:

bash
crewai create crew research_crew --classic

不要混合不同文档版本的文件布局,并假设 Loader 会自动发现它们。

Flow-first 生产应用

CrewAI 生产架构文档推荐 Flow-first 设计。Flow 可以拥有类型化状态、条件分支、等待、普通代码、模型调用与 Crew 调用。

flowchart LR A["已认证请求"] --> B["Flow 状态 + 政策"] B --> C["确定性准备"] C --> D["聚焦的 Crew"] D --> E["外部 Verifier"] E --> F{"是否验收"} F -->|"是"| G["授权提交"] F -->|"需要输入"| H["持久化暂停"] F -->|"否"| I["拒绝或补偿"] H --> B

Flow 本身也不是安全边界。身份、对象鉴权、网络政策、Secret 和持久副作用仍归应用负责。

构建最小 JSON-first 调研 Crew

示例把模型标识保留为部署值。请替换为固定 CrewAI 版本支持的 Provider/Model ID。

定义研究员

agents/researcher.jsonc:

jsonc
{
  "role": "{topic} 领域调研员",
  "goal": "收集相关论断,并为每条论断附上来源 URL",
  "backstory": "你区分有来源事实与分析,并明确标记证据缺失。",
  "llm": "provider/model-id",
  "tools": ["SerperDevTool"],
  "settings": {
    "verbose": false,
    "allow_delegation": false,
    "max_iter": 6,
    "max_execution_time": 180
  }
}

Tool 名称与设置属于 Runtime 契约,必须按精确版本核验。自定义 Tool 可以在项目加载时执行本地代码,因此只运行可信 Crew 项目,并审查 tools/ 下的全部内容。

定义分析员

agents/analyst.jsonc:

jsonc
{
  "role": "{topic} 证据分析员",
  "goal": "把有来源的发现整理为简洁报告,不虚构证据",
  "backstory": "你拒绝没有来源的论断,并保留不确定性与分歧。",
  "llm": "provider/model-id",
  "settings": {
    "verbose": false,
    "allow_delegation": false,
    "max_iter": 4,
    "max_execution_time": 120
  }
}

分析员刻意没有搜索工具。它可以转换研究结果,却不能在已声明证据链之外静默抓取新来源。

定义任务与流程

crew.jsonc:

jsonc
{
  "name": "证据调研 Crew",
  "agents": ["researcher", "analyst"],
  "tasks": [
    {
      "name": "research",
      "description": "调研 {topic}。每条事实论断必须提供来源 URL,并简述该来源具体支持什么。",
      "expected_output": "包含 ## Findings、## Unverified 和 ## Sources 的 Markdown;每条 Finding 必须引用 URL。",
      "agent": "researcher"
    },
    {
      "name": "report",
      "description": "只使用 research 任务输出,删除无证据论断,并保留分歧与不确定性。",
      "expected_output": "包含 ## Findings、## Unverified 和 ## Sources 的报告,不新增事实论断。",
      "agent": "analyst",
      "context": ["research"],
      "output_file": "output/report.md",
      "markdown": true
    }
  ],
  "process": "sequential",
  "verbose": false,
  "inputs": {
    "topic": "检索系统评测"
  }
}

第二项任务依赖第一项,所以示例刻意使用 Sequential。给任务起两个角色名不会让它们自动并行。

Sequential 与 Hierarchical Process

官方 Processes 文档定义:

  • sequential:任务按声明顺序执行,并可把前一步输出传作上下文;
  • hierarchical:Manager LLM 或自定义 Manager Agent 负责规划、委派与验收。

当任务无法预先拆解,且可用 Worker 具有真正不同的能力时,Hierarchical 才有价值。它会增加模型调用、路由决策和潜在循环,因此迭代、请求速率、墙钟时间与费用上限必须在模型控制之外。

不能把 Manager 当作唯一 Verifier。Manager 仍是一次模型交互,可能与 Worker 共享盲点。最终产物应由确定性检查、可执行测试、来源复核或经过校准的评测器验证。

为什么生产指南强调 Flow-first

Crew Process 不是持久业务工作流。生产系统往往需要:

  • 进程重启后仍存在的类型化状态;
  • 幂等键与权威状态查询;
  • 等待用户输入或审批时暂停与恢复;
  • 基于可信政策而非模型文字的分支;
  • 取消与 Deadline;
  • 对部分已提交工作的补偿;
  • 用于重放与事故分析的版本化事件。

Flow 让这些状态转移显式化,Crew 则保持为聚焦的工作单元。外部副作用必须放在应用服务之后:Crew 可以起草邮件,但可信服务决定收件人、权限、最终内容、幂等和发送状态。

工具与数据安全

每个 Agent 最小权限

研究员只获得只读搜索。不能因为分析员的 Role 里写了“高级”,就给它 Shell、数据库写入或发布工具。能力由真实工具凭证和服务端政策决定。

把 Tool Output 当作不可信输入

搜索结果、文档、Issue 评论、网页、OCR 与其他 Agent 消息都可能包含 Prompt Injection。保留来源身份与信任元数据,用分隔符帮助模型理解,但鉴权必须留在 Prompt 之外。

Secret 留在工作区之外

通过批准的 Secret 机制加载 Provider Key。不要把它写进 crew.jsonc、Agent 文件、生成报告、Trace 或提交到仓库的 .env。还要确认 Observability 是否会导出 Prompt、Tool 参数或客户数据。

限制自定义代码

当前 JSON-first 文档明确提醒:Custom Tool Reference 会加载本地 Python。运行第三方 Crew 项目前,审查源码、依赖、网络权限、文件系统权限和锁文件。

输出契约与校验

expected_output 能改善指令,但不会自动验证结果。Task Guardrail 与结构化输出可以拒绝格式错误,应用仍需负责语义与政策检查。

对带来源报告,至少校验:

  • 必需章节存在;
  • 每条事实 Finding 都有允许的来源;
  • 来源确实被抓取,并真正支持论断;
  • 输出没有复制 Secret 或私有来源;
  • 重复与矛盾论断被解决或明确标记;
  • 报告在大小与时间预算内;
  • 评测器失败时进入复核,而不是静默放行。

可运行的 Go 报告门禁

下面的标准库程序校验生成 Markdown 的最小结构契约。传入文件路径时,它会检查真实 Crew 输出;不传参数时使用内置 Fixture。

go
package main

import (
	"fmt"
	"os"
	"regexp"
	"strings"
)

var sourceURL = regexp.MustCompile(`https://[^\s)]+`)

func validate(report string) (int, error) {
	for _, heading := range []string{"## Findings", "## Unverified", "## Sources"} {
		if !strings.Contains(report, heading) {
			return 0, fmt.Errorf("missing heading %q", heading)
		}
	}
	sources := sourceURL.FindAllString(report, -1)
	if len(sources) < 2 {
		return 0, fmt.Errorf("need at least two source URLs")
	}
	if strings.Contains(report, "TODO") || strings.Contains(report, "source needed") {
		return 0, fmt.Errorf("unresolved placeholder")
	}
	return len(sources), nil
}

func main() {
	report := `# Report
## Findings
- Retrieval quality must be evaluated separately from generation.
## Unverified
- None.
## Sources
- https://example.com/source-a
- https://example.org/source-b
`
	if len(os.Args) == 2 {
		data, err := os.ReadFile(os.Args[1])
		if err != nil {
			panic(err)
		}
		report = string(data)
	}

	count, err := validate(report)
	if err != nil {
		panic(err)
	}
	fmt.Printf("report=valid sources=%d\n", count)
}

预期输出:

text
report=valid sources=2

这个门禁只检查结构,不证明事实为真。仍需逐条确认来源是否真正支持对应论断。

评测多 Agent 是否值得

至少比较三条基线:

  1. 可行时的不含模型确定性工作流;
  2. 使用合并指令与最少工具的单 Agent;
  3. 候选 Crew 或 Flow。

统一 Case、模型快照、工具、Timeout、输出契约与评测器,测量:

  • 任务成功率与高影响错误率;
  • 来源支持率与引用精度;
  • Task 交接损失;
  • 循环、重试与超时率;
  • p95 完成时间;
  • 模型与工具总调用数;
  • 单个合格结果成本;
  • 操作员复核时间。

只有角色隔离、并行工作或动态委派带来的目标收益,足以支付协调与运维成本时,多 Agent 架构才成立。

生产检查清单

  1. 固定 CrewAI、CLI、Python、Provider SDK、Tool 与 Model ID。
  2. 明确选择 JSON-first 或 Classic 布局,不混用教程。
  3. 状态、分支、等待或恢复跨越 Crew 时使用 Flow。
  4. Tool Credential 按任务限权,每个 Tool 内部强制鉴权。
  5. 设置迭代、请求、时间、字节和费用上限。
  6. 持久状态留在模型上下文之外,对未知结果做权威对账。
  7. 在模型之外校验结构化输出与业务语义。
  8. Trace 脱敏并限量,测试删除传播和租户隔离。
  9. 与单 Agent 和确定性基线比较。
  10. 先 Shadow、再灰度,并准备回滚。

常见问题

新项目应该从 Crew 还是 Flow 开始?

从应用边界判断。小型独立协作可以先用 JSON-first Crew;系统一旦需要持久状态、分支、等待、多个 Crew 或恢复,就应让 Flow 成为外层控制面。

allow_delegation: false 能强制安全边界吗?

不能。它只限制一种框架行为,无法认证调用者、限制 Tool Credential、授权对象或隔离代码执行。这些属性必须由可信服务与基础设施强制执行。

复杂任务是否更适合 Hierarchical 模式?

只有动态分配能改善实测结果时才适合。它会增加 Manager 模型、调用、延迟与循环风险,应与 Sequential Crew、显式分支 Flow 和单 Agent 对照。

Task Guardrail 可以替代应用校验吗?

不能。Guardrail 能拒绝输出并请求重试,但它仍位于框架执行路径内。鉴权、来源核验、业务不变量与持久副作用仍属于应用边界。

CrewAI 升级应该怎样测试?

固定新旧环境,重放符合权限要求的 Fixture,比较任务输出、Tool Call、状态转移、重试、Token、延迟与失败恢复,并核对部署项目实际使用的 JSON-first 与 Flow Loader。

一手资料