升级 CrewAI

如何在项目中升级 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，而锁文件解析到 1.11.1，那么运行 crewai install 会让你永远停留在 1.11.1，即使已有 1.14.4 可用。

要真正升级，你需要：

1. 更新 pyproject.toml 中的版本约束
2. 重新解析锁文件
3. 同步 venv

uv add 一次完成全部三步。

如何升级你的项目

# Bump the constraint and re-lock in one command
uv add "crewai[tools]>=1.14.4"

# Sync the venv (crewai install calls uv sync under the hood)
crewai install

# Verify
uv pip show crewai
# → Version: 1.14.4

把 [tools] 替换成你项目实际使用的 extras（例如 [tools,anthropic]）。如果不确定，请查看 pyproject.toml 的 dependencies 列表。

NOTE

uv add 会原子性地同时更新 pyproject.toml 和 uv.lock。如果你手动编辑 pyproject.toml，仍需运行 uv lock --upgrade-package crewai 重新解析锁文件，之后 crewai install 才会采用新版本。

升级全局 CLI

全局 CLI 与你的项目彼此独立。用下面的命令升级它：

uv tool install crewai --upgrade

如果升级后你的 shell 提示 PATH 相关警告，请刷新它：

uv tool update-shell

这不会触及项目 venv——你仍需要在项目内执行 uv add + crewai install。

验证两者是否同步

# Global CLI version
crewai --version

# Project venv version
uv pip show crewai | grep Version

它们不必一致——但项目 venv 的版本才决定运行时的行为。

NOTE

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

---

破坏性变更与迁移说明

大多数升级只需要小幅调整。下面这些领域是最容易出现静默失败或令人困惑的 traceback 的地方。

导入路径：工具与 BaseTool

工具的规范导入位置是 crewai.tools。旧路径仍会出现在教程中，但应当更新。

# Before
from crewai_tools import BaseTool
from crewai.agents.tools import tool

# After
from crewai.tools import BaseTool, tool

@tool 装饰器和 BaseTool 子类都位于 crewai.tools。AgentFinish 及其他智能体内部符号不再属于公开接口——如果你之前导入它们，请改用事件监听器或 Task 回调。

Agent 参数变化

from crewai import Agent

agent = Agent(
    role="Researcher",
    goal="Find authoritative sources on {topic}",
    backstory="You are a careful, source-driven researcher.",
    llm="gpt-4o-mini",   # string model name OR an LLM object
    verbose=True,        # bool, not an int level
    max_iter=15,         # default has changed across versions — set explicitly
    allow_delegation=False,
)

• llm 既可以接受字符串形式的模型名（通过已配置的服务商解析），也可以接受 LLM 对象以实现更精细的控制。
• verbose 是普通的 bool。传入整数不再切换日志级别。
• max_iter 的默认值在不同版本之间有过变化。如果你的智能体在首次工具调用后就静默停止循环，请显式设置 max_iter。

Crew 参数

from crewai import Crew, Process

crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,   # or 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 且使用非默认嵌入服务商时，需要 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="Write an article about {topic}",
    expected_output="A short article with a title and body",
    agent=writer,
    output_pydantic=Article,        # the class, NOT an instance
    output_file="output/article.md",
)

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

记忆与嵌入器配置

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

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

在 .env 文件中设置相关服务商凭证（OPENAI_API_KEY、OLLAMA_HOST 等）。记忆存储路径默认位于项目本地。用 1536 维嵌入创建的既有本地记忆存储，可能与使用 3072 维的默认 OpenAI text-embedding-3-large 嵌入器不兼容。如果遇到维度不匹配，请删除项目的记忆目录、运行 crewai reset-memories -m，或在迁移之前显式配置较旧的嵌入器模型。