1.5 快速入门：环境搭建与第一个 Crew

1.5 快速入门：环境搭建与第一个 Crew

本节约处在第一章最后一站，也是全书第一个能跑的代码。前面四节都在讲"为什么"和"是什么"，这里把环境装好，让一个最小 Crew 真正吐出结果。我们主张：学任何框架都该先让它动起来，再回头抠细节，否则概念永远是悬空的。

先确认环境。CrewAI 需要

先确认环境。CrewAI 需要 Python 3.10 及以上，官方推荐用虚拟环境隔离依赖，避免和你机器上别的包打架。

# 新建并激活虚拟环境（Windows 用后一行）
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 安装核心包
pip install crewai

# 如需官方工具集（搜索、抓取等），再装这个
pip install 'crewai[tools]'
​

装完后第一件事不是写业务，而是确认模型凭证可用。CrewAI 默认走 OpenAI 兼容接口，把凭证放进环境变量最干净，别硬编码进代码：

# 在终端导出，或写进 .env 文件（不要提交到仓库）
export OPENAI_API_KEY="sk-你的密钥"
export OPENAI_MODEL_NAME="gpt-4o-mini"   # 可选，控制默认模型
​

现在写第一个 Crew。它只做一

现在写第一个 Crew。它只做一件事：给定一个数，让"翻译官"把它用一句话解释给外行听。极简，但包含了 Agent、Task、Crew、Process 四个要素，是后面所有例子的种子。

from crewai import Agent, Task, Crew, Process

# 一个角色：负责把专业内容讲成人话
explainer = Agent(
    role="科普翻译",
    goal="用一句生活化的话解释技术概念",
    backstory="擅长用类比，但不堆术语",
    verbose=True,
    allow_delegation=False,
)

# 一个任务：解释传入的概念
explain_task = Task(
    description="用一句话向非技术背景的朋友解释 {concept}",
    expected_output="一句不超过三十字的中文解释",
    agent=explainer,
)

crew = Crew(
    agents=[explainer],
    tasks=[explain_task],
    process=Process.sequential,
    verbose=True,
)

# 真正启动；inputs 里的键对应任务描述里的 {concept}
result = crew.kickoff(inputs={"concept": "向量数据库"})
print("产出：", result)
​

把这段存成 first_crew.py 运行，控制台会先打出角色思考和工具调用过程（verbose=True 的效果），最后 result 是一段字符串，即那句解释。第一次看到模型按你的角色设定说话，多智能体这件事就从抽象变具体了。

跑通后，我们故意加一个会出错的写法，提前认识最常见的两类坑：

# 坑一：任务里的占位符没在 kickoff 的 inputs 中提供
bad_task = Task(
    description="解释 {concept} 和 {another}",  # another 没有给值
    expected_output="一句话",
    agent=explainer,
)

# 解决：确认 OPENAI_API_KEY 已导出，或显式传 llm=LLM(...)
​

这两个坑的根因不同：第一个是输入契约没对齐，属于"任务定义"问题；第二个是运行环境缺依赖，属于"配置"问题。后续第四章会专门讲错误处理与调试，但你现在就该养成习惯——每个 {占位符} 都要在 inputs 里有对应键，否则 Crew 启动即崩。

如果想更进一步，把单角色扩成双角色，体会"依赖"长什么样。下面让"研究员"先给要点，"写手"再据此成稿：

from crewai import Agent, Task, Crew, Process

researcher = Agent(role="研究员", goal="列要点", backstory="简洁", verbose=True)
writer = Agent(role="写手", goal="扩写成段", backstory="连贯", verbose=True)

t_research = Task(description="列出 {topic} 的三个要点", expected_output="三条要点", agent=researcher)
t_write = Task(description="把要点扩成一段说明", expected_output="一段两百字说明", agent=writer, context=[t_research])

crew = Crew(agents=[researcher, writer], tasks=[t_research, t_write], process=Process.sequential)
# crew.kickoff(inputs={"topic": "边缘计算"})
​

注意 t_write 的 context=[t_research]：它告诉框架"写手拿到的输入是研究员那步的产出"，而不是重新去想。这就是 CrewAI 处理依赖的方式——显式、可读、可测。

到这里，第一章的五站已经走完：动机、四要素、对比、跑通。你已经具备读第二章的资格。我们建议下一步不要急着上复杂业务，而是先照 3.1 到 3.3 把"定义 Agent、编排 Task、组建 Crew"这三件事分别练熟，每个都从小到能一眼看懂开始，再逐步加角色、加工具、加流程分支。

一个收尾提醒：第一个 Crew

一个收尾提醒：第一个 Crew 能跑不算学会了，能预测它的输出、能解释每一步为什么那样输出，才算。带着"我能不能解释清楚"的标准去读第二章，组件原理会读得更快。

跑通之后该做什么

第一个 Crew 能跑只是起点。我们建议立刻做两件事：把输入换成三个不同主题各跑一遍，观察产出结构是否稳定；再把 verbose 关掉重跑，确认没有依赖日志才能看懂结果。稳定且自解释，才算真跑通。

# 冒烟测试：换输入验证结构稳定
for t in ["储能", "低空经济", "AI 制药"]:
    r = crew.kickoff(inputs={"concept": t})
    assert len(str(r)) > 0
​

这一步花十分钟，能挡掉后面一堆"为什么这次不一样"的疑问。把第一个 Crew 当成探针，而不是当成产品。