用 CrewAI 搭建第一个多 Agent 研究报告工作流

这篇教程从 CrewAI 官方 quickstart 出发，带你在本地创建一个最小可跑的研究报告工作流：Flow 负责组织执行流程，Crew 中的 researcher agent 负责研究任务，最后把 Markdown 报告写入 output/report.md。

本文不会做云端 AMP 部署，不会要求你 clone CrewAI 大仓库，也不会把演示主题换成真实敏感业务资料。你可以把本文最后的任务块复制给自己的 AI Agent，让它在你的电脑上按步骤检查环境、创建项目、配置 .env、运行和验证。

官方来源：

CrewAI GitHub: <https://github.com/crewAIInc/crewAI>
CrewAI Installation: <https://docs.crewai.com/en/installation>
CrewAI Quickstart: <https://docs.crewai.com/en/quickstart>
CrewAI Flows: <https://docs.crewai.com/en/concepts/flows>

你会做成什么

你会得到一个本地 CrewAI 示例项目，运行后生成一份 Markdown 研究报告：

$env:USERPROFILE\ai-lab\crewai-report-flow\
  latest_ai_flow\
    .env
    output\
      report.md

工作流的最小结构如下：

CrewAI research report flow 自制流程示意图，不是官方界面截图

这张图是为本文自制的流程示意图，不是 CrewAI 官方界面截图，也不是软件运行截图。它只帮助你理解 quickstart 中的关系：输入 topic，Flow 管理状态，researcher agent 通过 Serper 做外部搜索，并调用模型 provider，最后输出 output/report.md。

本教程的成功标准很明确：

你能确认本机 Python 版本满足 CrewAI 要求：>=3.10 且 <3.14。
你能安装并验证 uv 与 CrewAI CLI。
你能用 crewai create flow latest-ai-flow 创建 quickstart 项目。
你能在项目根目录完成 crewai install。
你能配置 .env 中的 SERPER_API_KEY 和模型 provider keys。
你能运行 crewai run。
你能检查到 output/report.md 已生成。

重要边界：这不是生产部署教程，也不是让你把公司资料交给外部搜索和模型服务。外部搜索会把 query 发给 Serper；模型 provider 会收到你输入的主题、提示词和任务上下文。演示主题请使用公开、低敏、可测试的主题。

适合谁

适合这些读者：

产品经理：想理解多 Agent 工作流如何从主题到报告输出。
运营和内容负责人：想把公开资料研究、选题调研、竞品摘要变成可复用流程。
项目负责人：想判断 CrewAI 是否适合团队内部做研究报告、资料汇总或自动化分析。
初级开发者：会打开终端，能按命令创建 Python 项目，但还不熟悉 Agent 框架。

不适合这些场景：

你现在就要做公网生产部署。
你要把真实客户资料、内部合同、未发布产品方案作为演示输入。
你希望跳过 API Key、Python 环境和命令行配置。
你想直接复制官方文档全文，而不是建立一个最小可跑的理解路径。

开始前准备

你需要准备什么

先准备这些内容：

项目	用途	注意事项
Python `>=3.10` 且 `<3.14`	CrewAI 运行要求	低于 3.10 或达到 3.14 及以上都不要继续
`uv`	CrewAI 官方安装路径使用的工具	安装命令会从网络下载工具，执行前先确认
CrewAI CLI	创建和运行 quickstart 项目	通过 `uv tool install crewai` 安装
`SERPER_API_KEY`	quickstart 中用于 web search	搜索 query 会发给 Serper
模型 provider keys	researcher agent 调用模型	provider 会收到输入内容和任务上下文

安全规则先定下来

请先把这几条当成硬规则：

不要把真实 API Key 发给 AI Agent 的聊天窗口。
不要让 AI Agent 在回复中回显真实 Key。
不要把 .env、截图、录屏、Markdown 笔记或 Git commit 里放入真实 Key。
.env 必须加入 .gitignore。
演示 topic 不要包含客户名称、内部报价、私有代码、个人隐私、未公开商业计划。
如果你让 AI Agent 代执行，它只能提示你在本机输入 Key，不能要求你把 Key 粘贴给它。

第一步：认识这个开源项目

CrewAI GitHub 页面快照显示：CrewAI 有 54.9k stars、2,619 commits、521 PR。这些数字只作为页面快照，不代表你阅读本文时的实时 GitHub 状态。

CrewAI README 对项目的核心定位是：CrewAI 是一个 Python framework，支持 Crews 和 Flows。

你可以这样理解：

概念	作用	本教程中的角色
Crews	负责 role-based agents	researcher agent 被组织成一个 crew
Flows	负责 event-driven automations	Flow 保存 topic，触发 researcher crew，接收输出

官方 quickstart 的重点不是先写复杂系统，而是先创建一个 latest-ai-flow 示例项目。这个示例会设置一个 topic，运行一个 researcher agent 的 crew，最后把 Markdown report 写到：

output/report.md

执行位置：此步骤只需要阅读，不需要运行命令。

预期结果：你能说清楚本教程要做的是一个本地研究报告 Flow / Crew 工作流，而不是云端部署或完整生产系统。

验证方法：继续前确认你不会把本教程理解成“自动爬取全网并发布报告”的系统。它只是一个最小可跑的研究报告示例。

第二步：准备本地或服务器环境

本教程默认在 Windows 本地演示，路径使用用户目录，不使用 C:\ 根目录：

$labRoot = Join-Path $env:USERPROFILE "ai-lab\crewai-report-flow"
New-Item -ItemType Directory -Force -Path $labRoot
Set-Location $labRoot

执行位置：PowerShell。

预期结果：当前目录进入：

$env:USERPROFILE\ai-lab\crewai-report-flow

验证方法：

Get-Location

你应该看到路径位于自己的用户目录下，并且末尾是：

ai-lab\crewai-report-flow

如果你在 macOS 或 Linux 上演示，可以使用：

mkdir -p ~/ai-lab/crewai-report-flow
cd ~/ai-lab/crewai-report-flow
pwd

如果你在自己的测试服务器上操作，也只建议在普通用户目录下创建实验目录，不要直接在系统根目录或生产站点目录中操作。本教程不包含 SSH、Nginx、systemd、公网域名或 AMP 部署。

接着检查 Python：

python --version

执行位置：准备好的实验目录中。

预期结果：输出类似：

Python 3.11.x

验证方法：版本必须满足 CrewAI 安装要求：

>=3.10 and <3.14

如果输出小于 3.10，或者已经是 3.14 及以上，先换到符合要求的 Python 环境，再继续。

安装 uv

Windows 官方安装命令是：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

执行位置：PowerShell。

预期结果：安装 uv 工具。

验证方法：

uv --version

重要提醒：这个命令会从网络下载并安装工具。公司电脑、受管设备或你不确定脚本来源时，先停下来确认，不要让 AI Agent 直接替你执行。

如果安装后出现 PATH warning，官方安装说明给出的处理方式是：

uv tool update-shell

执行后重新打开一个终端，再运行：

uv --version

macOS / Linux 官方安装命令是：

curl -LsSf https://astral.sh/uv/install.sh | sh

如果没有 curl，可以按官方说明使用 wget 路径。无论哪种系统，核心验证都一样：

uv --version

安装 CrewAI CLI

安装 uv 后，按 CrewAI 安装说明安装 CrewAI CLI：

uv tool install crewai

执行位置：任意终端目录均可，建议仍在实验目录。

预期结果：crewai 作为 uv tool 被安装。

验证方法：

uv tool list

你需要在列表中看到 crewai。如果终端仍然提示找不到 crewai，先处理 PATH，再重新打开终端验证：

uv tool update-shell
uv tool list

第三步：安装项目

回到实验目录：

$labRoot = Join-Path $env:USERPROFILE "ai-lab\crewai-report-flow"
Set-Location $labRoot

执行位置：PowerShell 的实验目录。

预期结果：当前目录是 crewai-report-flow。

验证方法：

Get-Location

创建 CrewAI quickstart Flow：

crewai create flow latest-ai-flow

执行位置：$env:USERPROFILE\ai-lab\crewai-report-flow。

预期结果：CrewAI CLI 创建一个名为 latest_ai_flow 的项目目录。

验证方法：

Get-ChildItem

你应该能看到：

latest_ai_flow

进入项目：

Set-Location .\latest_ai_flow

验证位置：

Get-Location

路径末尾应该是：

latest_ai_flow

先确认 quickstart 生成的项目结构存在。依赖安装放到第四步配置完示例代码和 .env 之后再执行，避免先安装、后发现文件还没有按 quickstart 调整。

验证方法：

Get-ChildItem
Test-Path .\src\latest_ai_flow\crews\content_crew\config\agents.yaml
Test-Path .\src\latest_ai_flow\crews\content_crew\config\tasks.yaml
Test-Path .\src\latest_ai_flow\crews\content_crew\content_crew.py
Test-Path .\src\latest_ai_flow\main.py

预期结果：你仍在 latest_ai_flow 项目根目录，并且 4 个待配置文件都返回 True。

第四步：配置必要参数

官方 quickstart 在创建 latest-ai-flow 后，不是直接运行默认模板，而是要求配置一个最小研究 crew 和 Flow。这里要处理两类配置：先配置 quickstart 示例代码，再配置 .env 中的 SERPER_API_KEY 和模型 provider keys。Serper 用于 web search；模型 provider 用于 researcher agent 调用模型生成报告。

配置 quickstart 示例代码

执行位置：latest_ai_flow 项目根目录。

这 4 个文件分别负责：

文件	作用	修改方式	验证点
`src/latest_ai_flow/crews/content_crew/config/agents.yaml`	定义 researcher agent 的角色、目标和背景	保留一个 `researcher` 配置，使用 `{topic}` 变量	能搜索到 `researcher:` 和 `{topic}`
`src/latest_ai_flow/crews/content_crew/config/tasks.yaml`	定义研究任务和输出文件	保留一个 `research_task`，指定 `agent: researcher` 和 `output_file: output/report.md`	能搜索到 `research_task:` 和 `output/report.md`
`src/latest_ai_flow/crews/content_crew/content_crew.py`	把 YAML 配置接到 Crew 类，并给 researcher 加 `SerperDevTool`	替换为单 agent、单 task、顺序执行的 crew	能导入 `SerperDevTool`，类名能被 `main.py` 引用
`src/latest_ai_flow/main.py`	定义 Flow state，设置 topic，运行 crew，打印输出路径	替换为 `LatestAiFlow`，从正确模块导入 `ResearchCrew`	import 路径和项目包名 `latest_ai_flow` 一致

先确认 4 个文件都存在：

Test-Path .\src\latest_ai_flow\crews\content_crew\config\agents.yaml
Test-Path .\src\latest_ai_flow\crews\content_crew\config\tasks.yaml
Test-Path .\src\latest_ai_flow\crews\content_crew\content_crew.py
Test-Path .\src\latest_ai_flow\main.py

预期结果：4 行都输出 True。

可以用编辑器逐个打开文件：

notepad .\src\latest_ai_flow\crews\content_crew\config\agents.yaml
notepad .\src\latest_ai_flow\crews\content_crew\config\tasks.yaml
notepad .\src\latest_ai_flow\crews\content_crew\content_crew.py
notepad .\src\latest_ai_flow\main.py

agents.yaml 的核心结构可以简化为：

researcher:
  role: >
    {topic} researcher
  goal: >
    Find current, credible information about {topic} and turn it into a clear report.
  backstory: >
    You are a careful researcher who checks public information and writes concise findings.

tasks.yaml 的核心结构可以简化为：

research_task:
  description: >
    Research {topic} with web search and summarize practical trends, tools, and implications.
  expected_output: >
    A markdown report with clear sections and no fenced code block around the whole document.
  agent: researcher
  output_file: output/report.md

content_crew.py 的核心结构可以简化为：

from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool


@CrewBase
class ResearchCrew:
    agents_config = "config/agents.yaml"
    tasks_config = "config/tasks.yaml"

    @agent
    def researcher(self) -> Agent:
        return Agent(
            config=self.agents_config["researcher"],
            tools=[SerperDevTool()],
            verbose=True,
        )

    @task
    def research_task(self) -> Task:
        return Task(config=self.tasks_config["research_task"])

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,
            verbose=True,
        )

main.py 的核心结构可以简化为：

from pydantic import BaseModel

from crewai.flow import Flow, listen, start

from latest_ai_flow.crews.content_crew.content_crew import ResearchCrew


class ResearchFlowState(BaseModel):
    topic: str = ""
    report: str = ""


class LatestAiFlow(Flow[ResearchFlowState]):
    @start()
    def prepare_topic(self):
        self.state.topic = "AI Agents"
        print(f"Topic: {self.state.topic}")

    @listen(prepare_topic)
    def run_research(self):
        result = ResearchCrew().crew().kickoff(inputs={"topic": self.state.topic})
        self.state.report = result.raw
        print("Research crew finished.")

    @listen(run_research)
    def summarize(self):
        print("Report path: output/report.md")


def kickoff():
    LatestAiFlow().kickoff()


def plot():
    LatestAiFlow().plot()


if __name__ == "__main__":
    kickoff()

如果你的项目包名不是 latest_ai_flow，必须同步修改 main.py 里的导入路径。本文使用官方 quickstart 命令创建项目，因此默认包名就是 latest_ai_flow。

配置完后做静态验证，不运行项目代码：

Select-String -Path .\src\latest_ai_flow\crews\content_crew\config\agents.yaml -Pattern 'researcher|{topic}'
Select-String -Path .\src\latest_ai_flow\crews\content_crew\config\tasks.yaml -Pattern 'research_task|output/report.md'
Select-String -Path .\src\latest_ai_flow\crews\content_crew\content_crew.py -Pattern 'ResearchCrew|SerperDevTool'
Select-String -Path .\src\latest_ai_flow\main.py -Pattern 'latest_ai_flow.crews.content_crew.content_crew|ResearchCrew|output/report.md'

预期结果：每个文件都能找到对应关键字。若 main.py 的导入路径和项目目录不一致，先修正路径，再继续。

配置 `.env` 和本地依赖

先在项目根目录确认或创建 .env：

if (-not (Test-Path .\.env)) {
  New-Item -ItemType File -Path .\.env | Out-Null
}

执行位置：latest_ai_flow 项目根目录。

预期结果：项目根目录存在 .env 文件。

验证方法：

Test-Path .\.env

输出应为：

True

打开 .env：

notepad .\.env

写入配置时遵守这条规则：SERPER_API_KEY 是 quickstart 明确需要的变量；模型 provider key 的具体变量名以你选择的 provider 和生成项目中的配置为准，不要让 AI Agent 代替你编造真实 provider 配置。

示意结构如下，只展示占位符，不要把真实 Key 写进聊天记录：

SERPER_API_KEY=replace_with_your_serper_key

# Add the model provider key required by your selected CrewAI project config.
# Do not paste real keys into chat, screenshots, Markdown notes, or Git.
MODEL_PROVIDER_KEY_PLACEHOLDER=replace_with_your_model_provider_key

如果生成项目或你的 provider 文档要求的是其他变量名，请删除占位行，改成项目实际要求的变量名。不要保留 replace_with_... 这种占位值去运行。

把 .env 加入 .gitignore：

if (-not (Test-Path .\.gitignore)) {
  New-Item -ItemType File -Path .\.gitignore | Out-Null
}

if (-not (Select-String -Path .\.gitignore -Pattern '^\s*\.env\s*$' -Quiet)) {
  Add-Content -Path .\.gitignore -Value ".env"
}

执行位置：latest_ai_flow 项目根目录。

预期结果：.gitignore 包含 .env。

验证方法：

Select-String -Path .\.gitignore -Pattern '^\s*\.env\s*$'

你应该看到匹配结果，但不要打印 .env 里的真实内容。

最后做一次不泄密检查：

$envText = Get-Content -Raw .\.env
"SERPER_API_KEY present: " + ($envText -match '(?m)^SERPER_API_KEY=.+')
"Placeholder remains: " + ($envText -match 'replace_with_|PLACEHOLDER')

预期结果：

SERPER_API_KEY present: True
Placeholder remains: False

如果 Placeholder remains 是 True，说明你还没有把占位符换成真实本地配置，先不要运行。

配置完代码和 .env 后，再安装项目依赖：

crewai install

执行位置：latest_ai_flow 项目根目录。

预期结果：CrewAI 根据项目配置安装运行所需依赖。

验证方法：

Get-Location
Get-ChildItem

确认当前路径仍是 latest_ai_flow，并且没有跳到别的项目目录。

第五步：启动服务

这里的“启动服务”不是启动网页服务，也不会打开后台管理界面；CrewAI 在这里是运行本地 Flow / Crew 工作流，让 researcher agent 完成研究任务并写出 output/report.md。

CrewAI quickstart 的运行命令是：

crewai run

执行位置：latest_ai_flow 项目根目录。

预期结果：CrewAI 运行 Flow，Flow 设置 topic，调用 researcher agent 的 crew，研究任务会用到 Serper web search 和模型 provider，最终写出 Markdown report。

验证位置：

Get-Location

必须确认当前目录仍是：

latest_ai_flow

再运行：

crewai run

安全提醒：

外部搜索会把搜索 query 发给 Serper。
模型 provider 会收到主题、上下文和提示内容。
不要把敏感业务资料作为演示主题。
如果运行时要求重新输入或确认 provider 配置，不要把真实 Key 粘贴给 AI Agent 代看。

本文没有实际运行 CrewAI，因此不声称这里一定会输出某段固定日志。你只需要关注最终文件是否生成。

第六步：验证是否成功

运行结束后检查输出文件：

Test-Path .\output\report.md

执行位置：latest_ai_flow 项目根目录。

预期结果：

True

查看文件信息：

Get-Item .\output\report.md | Select-Object FullName, Length, LastWriteTime

预期结果：Length 大于 0，LastWriteTime 是刚刚运行后的时间。

只预览前几行，不要把可能包含敏感内容的完整报告直接贴到公开聊天里：

Get-Content .\output\report.md -TotalCount 40

预期结果：你能看到 Markdown 报告内容。

再做一次敏感信息检查：

Select-String -Path .\output\report.md -Pattern 'API_KEY|SERPER|sk-|token|secret'

预期结果：没有匹配结果。如果报告里出现 Key、token、secret 或不该公开的内部信息，先停止分享，删除敏感内容后再继续。

最后确认 .env 没有被 Git 跟踪：

git status --short

预期结果：如果这是一个 Git 项目，.env 不应该出现在待提交列表里。若 .env 出现在列表中，先检查 .gitignore，不要提交。

常见问题与排查

Python 版本不符合要求

现象：

Python 3.9.x

或：

Python 3.14.x

原因：CrewAI requires Python >=3.10 and <3.14。

Windows 上经常装了多个 Python，不要只看一个 python --version。先列出 Python Launcher 能找到的版本：

py -0p

如果列表里有 Python 3.11，可以明确检查：

py -3.11 --version

预期结果：输出类似 Python 3.11.x。如果你要让 CrewAI 使用这个版本，再在后续环境创建或命令执行中明确使用同一个 Python 版本，不要让 python、py、uv 指向三个不同环境。

换到符合要求的 Python 环境后再执行：

uv tool install crewai
crewai create flow latest-ai-flow

验证：实际用于项目的 Python 输出在 3.10 到 3.13 范围内。

`uv` 安装后命令不可用

现象：

uv: The term 'uv' is not recognized

处理：

uv tool update-shell

然后关闭当前终端，重新打开 PowerShell，再验证：

uv --version
uv tool list

预期结果：能看到 uv 版本，并能在 tool list 中看到已安装工具。

`crewai` 命令不可用

现象：

crewai: The term 'crewai' is not recognized

处理：

uv tool list
uv tool update-shell

如果 uv tool list 里没有 crewai，重新安装：

uv tool install crewai
uv tool list

验证：列表中出现 crewai，并且重新打开终端后可以执行 crewai。

Windows 上 `chroma-hnswlib` 或 C++ Build Tools 构建失败

现象：crewai install 过程中出现 chroma-hnswlib、hnswlib、Microsoft Visual C++ Build Tools、cl.exe、CMake 或 native build 相关错误。

原因：某些依赖在 Windows 上可能需要可用的 C++ 构建工具，或者当前 Python 版本没有匹配的预编译 wheel。

处理顺序：

python --version
py -0p
crewai install

先确认 Python 版本仍在 >=3.10 且 <3.14 范围内，并优先使用常见稳定版本，例如 Python 3.11。不要为了修一个构建错误就全局乱装很多包。若错误明确要求 C++ Build Tools，再安装 Microsoft C++ Build Tools，并重开终端后回到项目根目录重新运行：

crewai install

验证：安装完成后再执行 crewai run，不要跳过 crewai install。

忘记进入项目根目录

现象：执行 crewai install 或 crewai run 时找不到项目配置。

处理：

$projectRoot = Join-Path $env:USERPROFILE "ai-lab\crewai-report-flow\latest_ai_flow"
Set-Location $projectRoot
Get-Location

验证：路径末尾是 latest_ai_flow，再运行：

crewai install
crewai run

`.env` 缺少 Serper 或模型 provider key

现象：运行时提示搜索或模型 provider 相关配置缺失。

处理：打开 .env，确认：

notepad .\.env

至少要处理两类配置：

SERPER_API_KEY：quickstart 用于 web search。
模型 provider keys：按生成项目和所选 provider 的要求填写。

验证时不要打印真实 Key：

$envText = Get-Content -Raw .\.env
"SERPER_API_KEY present: " + ($envText -match '(?m)^SERPER_API_KEY=.+')
"Placeholder remains: " + ($envText -match 'replace_with_|PLACEHOLDER')

预期结果：

SERPER_API_KEY present: True
Placeholder remains: False

`ModuleNotFoundError: crewai_tools`

现象：运行时报错：

ModuleNotFoundError: No module named 'crewai_tools'

原因：quickstart 的 content_crew.py 使用 SerperDevTool，它来自 crewai_tools。这通常意味着项目依赖没有按 pyproject.toml 正确安装，或者你没有在项目根目录运行 crewai install。

处理：

Get-Location
Test-Path .\pyproject.toml
Select-String -Path .\pyproject.toml -Pattern 'crewai|crewai-tools|crewai_tools'
crewai install

不要盲目执行全局 pip install crewai_tools。先让项目自己的 pyproject.toml 和 crewai install 接管依赖，避免把全局 Python、uv tool 环境和项目环境混在一起。

验证：重新运行前确认仍在 latest_ai_flow 项目根目录：

Get-Location
crewai run

`output/report.md` 没有生成

现象：

Test-Path .\output\report.md

输出：

False

排查顺序：

Get-Location
Test-Path .\.env
Test-Path .\output

然后回看 crewai run 的终端错误，重点检查：

是否在 latest_ai_flow 根目录运行。
Python 版本是否符合要求。
crewai install 是否完成。
.env 是否包含 Serper 和模型 provider keys。
4 个 quickstart 文件是否按本文配置，尤其是 tasks.yaml 的 output_file: output/report.md。
main.py 是否从正确的 latest_ai_flow.crews.content_crew.content_crew 路径导入 ResearchCrew。
外部网络是否能访问 Serper 和模型 provider。

验证：修复后重新运行：

crewai run
Test-Path .\output\report.md

telemetry 和分享配置边界

CrewAI 官方 telemetry 说明里提到，默认匿名 telemetry 不应包含 prompts、task descriptions、agent backstories/goals、API calls、responses、环境变量或 secrets；但如果启用 share_crew，会收集更详细的 crew 和 task 信息，可能包含你写入配置、任务和输出里的敏感内容。

严格环境可以在运行前设置：

$env:OTEL_SDK_DISABLED = "true"

或者只关闭 CrewAI telemetry：

$env:CREWAI_DISABLE_TELEMETRY = "true"

验证：这类环境变量只在当前终端会话生效时，可以用下面命令查看：

$env:OTEL_SDK_DISABLED
$env:CREWAI_DISABLE_TELEMETRY

不要为了“分享运行效果”启用会额外收集 crew/task 细节的分享类配置，也不要把真实业务 topic、agent backstory、task description 或输出报告放进会被分享的配置里。

AI Agent 想让你把 Key 发给它

现象：你的 AI Agent 要求你把真实 API Key 粘贴到聊天里，让它帮你写 .env。

处理：拒绝。让 Agent 只给出 .env 模板和本地编辑命令，真实 Key 由你在本机编辑器里输入。

可以对 Agent 说：

不要让我把真实 API Key 发给你。请只给我本地编辑 .env 的步骤和占位模板。你不得在回复中回显真实 Key。

验证：聊天记录里不出现真实 Key、token、secret。

不要照搬的部分

不要照搬这些做法：

不要把官方 quickstart 的演示 topic 换成公司真实项目、客户名单、内部报价或未公开战略。
不要把 .env 内容贴进聊天记录，让 AI Agent 帮你“检查一下 Key 对不对”。
不要把 output/report.md 原文发布到外部平台，除非你确认其中没有敏感输入、搜索内容或模型输出。
不要把本地 quickstart 当成生产部署方案。本教程不包含 AMP 部署、云端运行、权限管理、日志审计、限流、备份、监控和成本控制。
不要 clone CrewAI 大仓库来完成这篇教程；quickstart 只需要 CrewAI CLI 创建示例项目。
不要在 C:\ 根目录、生产项目目录或公司共享目录里直接试验。
不要让 AI Agent 安装工具、修改全局环境或访问第三方服务前不经确认就执行。

可以保留的部分：

先用公开主题做最小可跑验证。
把 Flow、Crew、researcher agent、Serper、model provider 和 output/report.md 的关系讲清楚。
把每一步都写成可复制命令、预期结果和验证方法。
把 .env、Key 保护、外部搜索和模型 provider 数据边界写在教程前面。

交给你的 AI Agent 继续执行

下面这段可以复制给你自己的 AI Agent。它的目标是在你的本机按本文创建并验证 CrewAI quickstart 项目。复制前请确认：不要把真实 API Key 一起发给 Agent。

你是我的本地 CrewAI quickstart 执行助手。请只在我的用户目录下操作，不要使用 C:\ 根目录，不要 SSH，不要部署公网，不要 clone CrewAI 大仓库，不要安装未确认的大依赖，不要运行与本教程无关的第三方项目代码。

目标：
在 Windows PowerShell 中创建并运行 CrewAI 官方 quickstart 的 latest-ai-flow 示例，配置 researcher crew 和 Flow，最终验证 output/report.md 是否生成。

默认工作目录：
$env:USERPROFILE\ai-lab\crewai-report-flow

必须遵守：
1. 所有命令执行前先告诉我执行位置、目的和可能影响。
2. 安装 uv 的官方 Windows 命令会从网络下载工具，执行前必须让我确认。
3. 需要安装 CrewAI CLI 时使用 uv tool install crewai。
4. 不要让我把真实 API Key 发到聊天记录。
5. 不要在回复中回显真实 API Key。
6. .env 必须加入 .gitignore。
7. 外部搜索会把 query 发给 Serper，模型 provider 会收到输入内容；演示 topic 不得包含敏感业务资料。
8. 不要启用 share_crew 等会额外收集 crew/task 细节的分享类配置；严格环境可提示我设置 OTEL_SDK_DISABLED=true。
9. 不要声称已经成功，除非你实际检查到 output/report.md 存在且 Length 大于 0。

执行步骤：
1. 检查 python --version，同时在 Windows 上执行 py -0p；如有 Python 3.11，执行 py -3.11 --version，确认 CrewAI 要求的 Python >=3.10 and <3.14。
2. 检查 uv --version；如果没有 uv，给出官方 Windows 安装命令并等待我确认。
3. 执行 uv tool install crewai，然后用 uv tool list 验证 crewai 已安装。
4. 创建目录 $env:USERPROFILE\ai-lab\crewai-report-flow 并进入。
5. 执行 crewai create flow latest-ai-flow。
6. 进入 latest_ai_flow，并检查这 4 个文件存在：src/latest_ai_flow/crews/content_crew/config/agents.yaml、src/latest_ai_flow/crews/content_crew/config/tasks.yaml、src/latest_ai_flow/crews/content_crew/content_crew.py、src/latest_ai_flow/main.py。
7. 按官方 quickstart 口径修改 agents.yaml：保留 researcher agent，并使用 {topic} 变量。
8. 修改 tasks.yaml：保留 research_task，绑定 agent: researcher，并设置 output_file: output/report.md。
9. 修改 content_crew.py：定义 ResearchCrew，加载 config/agents.yaml 和 config/tasks.yaml，并给 researcher 配置 SerperDevTool。
10. 修改 main.py：定义 Flow state，设置 topic，导入 latest_ai_flow.crews.content_crew.content_crew 中的 ResearchCrew，运行 crew，并打印 output/report.md 路径。
11. 静态检查导入路径和关键字：ResearchCrew、SerperDevTool、research_task、output/report.md、latest_ai_flow.crews.content_crew.content_crew。
12. 创建或编辑 .env。只给我占位模板；真实 SERPER_API_KEY 和模型 provider keys 由我在本机编辑器里输入。
13. 把 .env 加入 .gitignore。
14. 在不打印真实 Key 的前提下检查 SERPER_API_KEY 是否存在、是否还残留 replace_with_ 或 PLACEHOLDER。
15. 执行 crewai install。若遇到 chroma-hnswlib / C++ Build Tools 类构建错误，先检查 Python 版本和错误信息，不要盲目全局 pip install。
16. 执行 crewai run。若出现 ModuleNotFoundError: crewai_tools，先检查 pyproject.toml 和 crewai install，不要盲目全局 pip install。
17. 检查 Test-Path .\output\report.md。
18. 如果文件存在，用 Get-Item .\output\report.md | Select-Object FullName, Length, LastWriteTime 验证文件大小和时间。
19. 用 Select-String -Path .\output\report.md -Pattern 'API_KEY|SERPER|sk-|token|secret' 做敏感词检查。
20. 最后报告：执行过哪些命令、在哪个目录执行、4 个 quickstart 文件是否已配置、导入路径是否正确、是否生成 output/report.md、遇到的错误、未解决风险。

如果任何步骤需要安装工具、修改全局 PATH、访问第三方服务或产生 API 调用，请先停下来让我确认。

你会做成什么

适合谁

开始前准备

你需要准备什么

安全规则先定下来

第一步：认识这个开源项目

第二步：准备本地或服务器环境

安装 uv

安装 CrewAI CLI

第三步：安装项目

第四步：配置必要参数

配置 quickstart 示例代码

配置 .env 和本地依赖

第五步：启动服务

第六步：验证是否成功

常见问题与排查

Python 版本不符合要求

uv 安装后命令不可用

crewai 命令不可用

Windows 上 chroma-hnswlib 或 C++ Build Tools 构建失败

忘记进入项目根目录

.env 缺少 Serper 或模型 provider key

ModuleNotFoundError: crewai_tools

output/report.md 没有生成

telemetry 和分享配置边界

AI Agent 想让你把 Key 发给它

不要照搬的部分

交给你的 AI Agent 继续执行

其他教程

配置 `.env` 和本地依赖

`uv` 安装后命令不可用

`crewai` 命令不可用

Windows 上 `chroma-hnswlib` 或 C++ Build Tools 构建失败

`.env` 缺少 Serper 或模型 provider key

`ModuleNotFoundError: crewai_tools`

`output/report.md` 没有生成