CrewAI多智能体配置：用YAML定义角色并跑通第一个协作任务
CrewAI 的多智能体配置不是写一堆 Python 类，而是先在 agents.yaml 里定义每个角色的身份、目标和工具，再在 tasks.yaml 里描述任务和预期输出，最后用 Crew 把角色和任务串起来运行。
适合想让多个 AI 角色分工完成调研、写作、审核等流程的开发者。
下面从零跑通一个最小可运行配置。
先确认环境与依赖
CrewAI 依赖 Python 3.10 及以上版本，建议用虚拟环境隔离包。
执行以下命令检查版本并安装：
python3 --version
python3 -m venv crewai-env
source crewai-env/bin/activate
pip install crewai crewai-tools安装后可以用 pip show crewai 查看实际版本。
CrewAI 迭代较快，不同版本对配置文件字段的支持可能不同，遇到参数报错时优先核对当前安装版本的文档。
还需要准备一个大模型 API Key，例如 OpenAI 兼容接口。
把 Key 写入环境变量，不要直接硬编码在代码里：
export OPENAI_API_KEY="你的密钥"如果使用其他兼容接口，还需要设置 OPENAI_API_BASE 指向对应地址。
定义角色和任务文件
在项目目录下创建 config/agents.yaml，每个角色用键名区分。
下面配置一个调研员和一个写作者：
researcher:
role: 行业调研员
goal: 收集并整理指定主题的关键事实
backstory: 你擅长从公开信息中提取可验证的要点，不编造数据。
verbose: true
writer:
role: 技术写作者
goal: 根据调研要点写出结构清晰的中文说明
backstory: 你面向新手写作，语言直接，步骤明确。
verbose: true再创建 config/tasks.yaml，任务要写清描述和预期输出：
research_task:
description: 围绕“CrewAI 多智能体配置”整理三个核心配置步骤。
expected_output: 三条带简短说明的步骤列表。
agent: researcher
write_task:
description: 把调研结果改写成一段适合新手阅读的说明。
expected_output: 一段不超过 200 字的中文段落。
agent: writeragent 字段必须和 agents.yaml 中的键名完全一致，大小写不一致会导致角色找不到。
用 Crew 组装并运行
创建 main.py，加载 YAML 并实例化 Crew：
from crewai import Agent, Task, Crew
import yaml
with open("config/agents.yaml") as f:
agents_config = yaml.safe_load(f)
with open("config/tasks.yaml") as f:
tasks_config = yaml.safe_load(f)
researcher = Agent(config=agents_config["researcher"])
writer = Agent(config=agents_config["writer"])
research_task = Task(config=tasks_config["research_task"], agent=researcher)
write_task = Task(config=tasks_config["write_task"], agent=writer)
crew = Crew(
agents=[researcher, writer],
tasks=[research_task, write_task],
verbose=True
)
result = crew.kickoff()
print(result)运行 python main.py。
如果配置正确，终端会先输出调研员的工作过程，再输出写作者基于前一个任务结果生成的内容。kickoff() 默认按任务列表顺序执行，后一个任务可以读取前一个任务的输出。
容易踩坑的几个配置点
角色目标写得太空泛。goal 写成“帮助用户”这类描述，模型很难判断边界，输出会漂移。
尽量写成可判断的具体结果，例如“列出三条可验证的配置步骤”。
任务之间缺少依赖说明。
CrewAI 按列表顺序传递上下文，但如果任务描述里没有提到要使用前序结果，写作者可能忽略调研内容。
可以在 description 中明确写“基于上一个任务的输出”。
YAML 缩进错误。
YAML 对空格敏感，role、goal、backstory 必须保持相同缩进层级，冒号后要留一个空格。
用 python -c "import yaml; yaml.safe_load(open('config/agents.yaml'))" 可以先验证文件能否被正确解析。
API Key 未生效。
如果报认证失败，先在当前终端执行 echo $OPENAI_API_KEY 确认变量存在。
用 export 设置的变量只在当前会话有效，换终端后需要重新设置。
验证配置是否真正生效
运行结束后不要只看有没有报错。
检查三点：终端是否打印了两个角色各自的执行过程；
最终输出是否包含调研任务里要求的三条步骤；
写作者的内容是否引用了调研结果而不是凭空生成。
如果输出为空或角色没有按预期分工，先把 verbose 设为 True 观察执行日志，再逐个检查 YAML 键名、任务顺序和 agent 引用。
确认最小流程跑通后，再逐步增加角色、工具和更复杂的任务依赖。
