업그레이드 (Upgrading CrewAI)¶

CrewAI는 새 릴리스마다 새로운 기능을 꾸준히 내놓아요. 이 가이드는 설치본을 최신으로 유지하기 위한 실제 단계를 안내합니다 — CLI와 프로젝트의 가상 환경, 둘 다요. 처음부터 시작한다면 Installation을, 다른 프레임워크에서 넘어온다면 Migrating from 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에 머물러요. 실제로 업그레이드하려면 다음이 필요합니다:

pyproject.toml의 버전 제약을 갱신
lock 파일을 다시 해석(re-solve)
venv를 동기화

uv add는 이 세 가지를 한 번에 처리해요.

프로젝트 업그레이드 방법¶

# 제약을 올리고 다시 lock을 잡는 것을 한 명령으로
uv add "crewai[tools]>=1.14.4"

# venv 동기화 (crewai install은 내부적으로 uv sync를 호출)
crewai install

# 확인
uv pip show crewai
# → Version: 1.14.4

[tools]는 프로젝트가 쓰는 extras로 바꿔주세요(예: [tools,anthropic]). 잘 모르겠으면 pyproject.toml의 dependencies 목록을 확인해요.

uv add는 pyproject.toml과 uv.lock을 원자적으로 함께 갱신해요. pyproject.toml을 직접 수정했다면, crewai install이 새 버전을 받아오기 전에 uv lock --upgrade-package crewai로 lock 파일을 재해석해야 해요.

전역 CLI 업그레이드¶

전역 CLI는 프로젝트와 분리되어 있어요. 다음과 같이 업그레이드합니다:

uv tool install crewai --upgrade

업그레이드 후 셸이 PATH에 대해 경고하면, 새로고침해주세요:

uv tool update-shell

이 명령은 프로젝트의 venv를 건드리지 않아요. 프로젝트 안에서는 여전히 uv add + crewai install이 필요합니다.

둘이 동기화됐는지 확인¶

# 전역 CLI 버전
crewai --version

# 프로젝트 venv 버전
uv pip show crewai | grep Version

둘이 일치할 필요는 없어요. 하지만 런타임 동작에 중요한 것은 프로젝트 venv 버전입니다.

CrewAI는 Python >=3.10, <3.14가 필요해요. uv가 더 오래된 인터프리터로 설치됐다면, crewai install을 실행하기 전에 지원되는 Python으로 프로젝트 venv를 다시 만들어주세요.

Breaking Changes와 마이그레이션 노트¶

대부분의 업그레이드는 작은 조정만으로 충분해요. 아래 영역들이 조용히, 혹은 헷갈리는 traceback과 함께 깨지는 부분이에요.

import 경로: tools와 `BaseTool`¶

도구의 정식 import 위치는 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와 그 밖의 내부 에이전트 심볼은 더 이상 공개 표면에 포함되지 않아요. 이걸 import하고 있었다면, 이벤트 리스너나 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",   # 문자열 모델 이름 OR LLM 객체
    verbose=True,        # int 레벨이 아니라 bool
    max_iter=15,         # 기본값이 버전마다 바뀌었음 — 명시적으로 설정
    allow_delegation=False,
)

llm은 문자열 모델 이름(설정된 프로바이더로 해석) 또는 세밀한 제어를 위한 LLM 객체를 받아요.
verbose는 단순한 bool이에요. 정수를 넘긴다고 로그 레벨이 토글되지 않아요.
max_iter 기본값은 릴리스 사이에 변동됐어요. 첫 번째 도구 호출 후 에이전트가 조용히 루프를 멈추면 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를 쓰려면 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="Write an article about {topic}",
    expected_output="A short article with a title and body",
    agent=writer,
    output_pydantic=Article,        # 인스턴스가 아니라 클래스
    output_file="output/article.md",
)

output_pydantic은 클래스 자체를 받아요. Article(title="", body="")처럼 인스턴스를 넘기는 건 흔한 실수이고, 헷갈리는 검증 오류로 실패해요.

Memory와 embedder 설정¶

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 embedder와 호환되지 않을 수 있어요. 차원 불일치가 발생하면 프로젝트의 메모리 디렉터리를 삭제하거나, crewai reset-memories -m을 실행하거나, 마이그레이션할 때까지 예전 embedder 모델을 명시적으로 설정하세요.