跳转到主要内容

文档索引

获取完整文档索引： https://docs.crewai.com.cn/llms.txt

在深入了解之前，请使用此文件来浏览所有可用页面。

​
概述

CrewAI 会定期发布新功能。本指南将引导您完成保持安装版本更新的实用步骤——涵盖 CLI 和项目的虚拟环境。 如果您是首次安装，请参阅安装。如果您是从其他框架迁移而来，请参阅从 LangGraph 迁移。

​
您可能需要升级的两个方面

CrewAI 在您的计算机上有两处部署，它们分别独立升级
内容安装方式如何升级
全局 crewai CLIuv tool install crewaiuv tool install crewai --upgrade
项目虚拟环境 (venv) (代码运行环境)crewai install / uv syncuv add "crewai[...]>=X.Y.Z" 然后 crewai install
这两者常常会出现不同步的情况。运行 crewai --version 可查看 CLI 版本。在项目内运行 uv pip show crewai 可查看虚拟环境版本。如果它们不一致是正常的；对代码运行而言，重要的是虚拟环境的版本。

​
为什么仅运行 crewai install 无法升级

crewai install 是 uv sync 的一个轻量封装。它严格按照当前的 uv.lock 文件进行安装，并不会更改任何版本约束。 如果您的 pyproject.toml 中写着 crewai>=1.11.1 且锁定文件已解析为 1.11.1，那么即使 1.14.4 可用，运行 crewai install 也将使您永久停留在 1.11.1 版本。 要真正完成升级，您需要：
  1. 更新 pyproject.toml 中的版本约束
  2. 重新解析锁定文件
  3. 同步虚拟环境
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] 替换为您项目实际使用的扩展（例如 [tools,anthropic]）。如果不确定，请检查 pyproject.toml 中的 dependencies 列表。
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
这不会影响项目的虚拟环境——您仍然需要在项目内部运行 uv add + crewai install。

​
验证两者是否同步

# Global CLI version
crewai --version

# Project venv version
uv pip show crewai | grep Version
它们不需要匹配——但项目虚拟环境的版本决定了运行时的行为。
CrewAI 要求 Python >=3.10, <3.14。如果 uv 是在较旧的解释器上安装的，请在运行 crewai install 前使用受支持的 Python 版本重新创建项目虚拟环境。

​
重大变更与迁移说明

大多数升级只需少量调整。以下领域可能会发生静默崩溃或报错信息令人困惑的情况。

​
导入路径：工具与 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 和其他内部 Agent 符号不再作为公共 API 提供——如果您之前导入了它们，请改用事件监听器或 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-small"}},
)
  • 使用 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 嵌入，则必须传入 embedder 配置。 
crew = Crew(
    agents=[...],
    tasks=[...],
    memory=True,
    embedder={
        "provider": "ollama",
        "config": {"model": "nomic-embed-text"},
    },
)
请在 .env 文件中设置相关的提供程序凭据（如 OPENAI_API_KEY, OLLAMA_HOST 等）。默认情况下，内存存储路径是项目本地的——如果您更改了嵌入器，请删除项目的内存目录，因为不同的维度无法混合。