升级 CrewAI

概述

CrewAI 会持续发布新能力。本指南会带你完成保持安装更新的实际步骤 - 包括 CLI 和项目虚拟环境。

如果你是从零开始，请参见 安装。如果你来自其他框架，请参见 从 LangGraph 迁移。

---

你可能想升级的两样东西

CrewAI 在你的机器上有两个位置，它们是独立升级的：

内容	安装方式	升级方式
全局 crewai CLI	uv tool install crewai	uv tool install crewai --upgrade
项目 venv（你的代码运行在这里）	crewai install / uv sync	uv add "crewai[...]>=X.Y.Z" 然后 crewai install

这两者可以 - 而且经常会 - 失去同步。运行 crewai --version 查看 CLI 版本。进入项目后运行 uv pip show crewai 查看 venv 版本。如果它们不同，这是正常的；对运行时行为真正重要的是 venv 版本。

为什么单独运行 crewai install 不会升级

crewai install 只是 uv sync 的一个薄封装。它只会安装当前 uv.lock 文件所写明的内容 - 不会 提升任何版本约束。

如果你的 pyproject.toml 写的是 crewai>=1.11.1，而 lock 文件解析到的是 1.11.1，那么即使 1.14.4 已经可用，运行 crewai install 也会让你一直停留在 1.11.1。

要真正升级，你需要：

1. 更新 pyproject.toml 里的版本约束
2. 重新求解 lock 文件
3. 同步 venv

uv add 会一次性完成这三步。

如何升级你的项目

# 一条命令同时提升约束并重新锁定
uv add "crewai[tools]>=1.14.4"

# 同步 venv（crewai install 底层会调用 uv sync）
crewai install

# 验证
uv pip show crewai
# → Version: 1.14.4

把 [tools] 替换为你的项目使用的额外依赖，例如 [tools,anthropic]。如果不确定，请检查 pyproject.toml 中的 dependencies 列表。

Note

uv add 会原子性地同时更新 pyproject.toml 和 uv.lock。如果你手动编辑了 pyproject.toml，仍然需要运行 uv lock --upgrade-package crewai 重新求解 lock 文件，然后 crewai install 才会获取新版本。

升级全局 CLI

全局 CLI 与你的项目是分开的。用下面的命令升级它：

uv tool install crewai --upgrade

如果升级后 shell 提示 PATH 有问题，请刷新它：

uv tool update-shell

这不会触碰你项目的 venv - 你仍然需要在项目内执行 uv add + crewai install。

验证两者是否同步

# 全局 CLI 版本
crewai --version

# 项目 venv 版本
uv pip show crewai | grep Version

它们不需要完全一致 - 但真正影响运行时行为的是你的项目 venv 版本。

Note

CrewAI 需要 Python >=3.10, <3.14。如果 uv 是在较旧解释器下安装的，请先用受支持的 Python 重新创建项目 venv，再运行 crewai install。

---

破坏性变更与迁移说明

大多数升级只需要很小的调整。下面这些区域更容易静默失效，或者抛出令人困惑的 traceback。

导入路径：tools 和 BaseTool

工具的标准导入位置是 crewai.tools。较旧的路径仍可能在教程里出现，但应该更新。

# 之前
from crewai_tools import BaseTool
from crewai.agents.tools import tool

# 之后
from crewai.tools import BaseTool, tool

@tool 装饰器和 BaseTool 子类都位于 crewai.tools。AgentFinish 和其他内部 agent 符号不再属于公共接口 - 如果你曾经导入它们，请改用事件监听器或 Task 回调。

Agent 参数变更

from crewai import Agent

agent = Agent(
    role="研究员",
    goal="查找关于 {topic} 的权威来源",
    backstory="你是一位严谨、以来源为驱动的研究员。",
    llm="gpt-4o-mini",   # 字符串模型名 或 LLM 对象
    verbose=True,        # bool，不再是整数级别
    max_iter=15,         # 默认值在不同版本间有变动 - 请显式设置
    allow_delegation=False,
)

• llm 可以是字符串模型名（通过已配置的 provider 解析），也可以是 LLM 对象以获得更细粒度控制。
• verbose 是普通 bool。传入整数不再会切换日志级别。
• max_iter 的默认值在不同版本之间发生过变化。如果你的 agent 在第一次工具调用后就悄悄停止循环，请显式设置 max_iter。

Crew 参数

from crewai import Crew, Process

crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,   # 或 Process.hierarchical
    memory=True,
    cache=True,
    embedder={"provider": "openai", "config": {"model": "text-embedding-3-large"}},
)

• process=Process.hierarchical 需要 manager_llm= 或 manager_agent=。如果没有，kickoff 会在验证阶段报错。
• 当 memory=True 且你使用的不是默认 OpenAI text-embedding-3-large 嵌入时，必须提供 embedder 字典 - 见下方 Memory 与 embedder 配置。

Task 结构化输出

使用 output_pydantic、output_json 或 output_file 将任务结果约束为有类型的形状：

from pydantic import BaseModel
from crewai import Task

class Article(BaseModel):
    title: str
    body: str

write = Task(
    description="写一篇关于 {topic} 的文章",
    expected_output="一篇包含标题和正文的简短文章",
    agent=writer,
    output_pydantic=Article,        # 传入类本身，不是实例
    output_file="output/article.md",
)

output_pydantic 接收的是类本身。传入 Article(title="", body="") 是常见错误，会触发令人困惑的验证错误。

Memory 与 embedder 配置

如果 memory=True 且你没有使用默认的 OpenAI text-embedding-3-large embeddings，那么必须传入 embedder：

crew = Crew(
    agents=[...],
    tasks=[...],
    memory=True,
    embedder={
        "provider": "ollama",
        "config": {"model": "nomic-embed-text"},
    },
)

在 .env 文件中设置对应 provider 的凭证（OPENAI_API_KEY、OLLAMA_HOST 等）。默认情况下，Memory 存储路径是项目本地的。使用 1536 维 embeddings 创建的本地 memory 存储，可能与默认 OpenAI text-embedding-3-large embedder 不兼容，因为后者使用 3072 维。如果出现维度不匹配，请删除项目的 memory 目录，运行 crewai reset-memories -m，或者在迁移完成前显式配置旧版 embedder 模型。