설치하기

설치하기 (Installation)

CrewAI를 설치하고 첫 프로젝트를 만드는 방법을 알려드릴게요. 코딩 에이전트 설정부터 uv로 crewai CLI를 설치하고, JSON 기반 프로젝트를 생성·실행하는 과정까지 차근차근 따라가면 돼요.

출처: 문서

본문

코딩 에이전트에서 CrewAI 설정하기

Claude Code, Codex, Cursor 등 코딩 에이전트에 바로 붙여 넣을 수 있는 설정 프롬프트를 복사해 사용할 수 있어요. 공식 CrewAI 스킬을 설치하고 CLI를 확인한 뒤, 코드를 수정하기 전에 에이전트가 올바른 문서를 참조하도록 안내해 줘요.

비디오 튜토리얼

설치 과정을 단계별로 보여주는 비디오 튜토리얼을 시청하세요.

텍스트 튜토리얼

Python 버전 요구 사항

CrewAI는 Python >=3.10과 <3.14가 필요해요. 버전을 확인하는 방법은 다음과 같아요:

python3 --version

Python을 업데이트해야 한다면 python.org/downloads를 방문하세요.

OpenAI SDK 요구 사항

CrewAI 0.175.0은 openai >= 1.13.3이 필요해요. 의존성을 직접 관리한다면 import/런타임 문제를 피하기 위해 이 제약 조건을 만족시키는지 확인하세요.

CrewAI는 의존성 관리 및 패키지 처리 도구로 uv를 사용해요. 프로젝트 설정과 실행을 단순화해서 매끄러운 경험을 제공해 줘요. 아직 uv를 설치하지 않았다면 아래 step 1을 따라 빠르게 설정하고, 이미 있다면 step 2로 건너뛰면 돼요.

1. uv 설치하기

macOS/Linux: curl로 스크립트를 다운로드하고 sh로 실행하세요:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
시스템에 curl이 없다면 wget을 사용하세요:
```
wget -qO- https://astral.sh/uv/install.sh | sh
```
Windows: irm으로 스크립트를 다운로드하고 iex로 실행하세요:
```
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
문제가 생기면 UV 설치 가이드를 참조하세요.

2. CrewAI 설치하기 🚀

다음 명령으로 crewai CLI를 설치해요:
```
uv tool install crewai
```
PATH 경고가 나오면 셸을 업데이트하세요:
```
uv tool update-shell
```
Windows에서 chroma-hnswlib==0.7.6 빌드 에러(fatal error C1083: Cannot open include file: 'float.h')가 나면, Visual Studio Build Tools에 Desktop development with C++을 설치하세요.
crewai가 설치되었는지 확인하려면:
```
uv tool list
```
crewai v0.102.0 - crewai 같은 내용이 보여야 해요.
crewai를 업데이트하려면:
```
uv tool install crewai --upgrade
```
이건 전역(global) crewai CLI 툴만 업그레이드해요. 프로젝트 가상환경 내부의 crewai 버전을 올리려면 "Upgrading CrewAI in a project"를 참고하세요.

설치가 완료됐어요! 이제 첫 crew를 만들 준비가 됐네요. 🎉

CrewAI 프로젝트 만들기

crewai create crew는 이제 JSON 우선(JSON-first) crew 프로젝트를 만들어요. 에이전트는 agents/*.jsonc에, 태스크와 crew 레벨 설정은 crew.jsonc에 있으며, crewai run은 그 JSON 정의를 직접 로드해요.

1. 프로젝트 스캐폴딩 생성

crewai CLI 명령을 실행하세요:

crewai create crew < your_project_name >

다음 구조의 새 프로젝트가 만들어져요:

my_project/
├── .gitignore
├── .env
├── agents/
│   └── researcher.jsonc
├── crew.jsonc
├── knowledge/
├── pyproject.toml
├── README.md
├── skills/
└── tools/

더 오래된 Python/YAML 스캐폴드(crew.py, config/agents.yaml, config/tasks.yaml)가 필요하다면:
```
crewai create crew < your_project_name > --classic
```

2. 프로젝트 커스터마이즈

프로젝트에는 다음 필수 파일이 들어 있어요:

File	Purpose
`crew.jsonc`	crew, 태스크 순서, 프로세스, 입력 기본값 구성
`agents/*.jsonc`	각 에이전트의 역할, 목표, 배경, LLM, 툴, 동작 정의
`.env`	API 키와 환경 변수 저장
`tools/`	커스텀 `<name>` 툴용 선택적 Python 파일
`knowledge/`	에이전트용 선택적 지식 파일
`skills/`	crew에 적용되는 선택적 스킬 파일

crew.jsonc와 agents/의 파일을 편집해 crew의 동작을 정의하는 것부터 시작하세요.
에이전트와 태스크 텍스트에 {placeholder} 값을 사용하고, crew.jsonc의 inputs 아래에 기본값을 설정하세요. crewai run을 실행하면 누락된 값이 있으면 CLI가 입력을 요구해요.
API 키 같은 민감한 정보는 .env에 보관하세요.

3. crew 실행하기

crew를 실행하기 전에 반드시 먼저:
```
crewai install
```
추가 패키지가 필요하면:
```
uv add < package-name >
```
보충(공급망) 보안 조치로, CrewAI 내부 패키지는 pyproject.toml에 exclude-newer = "3 days"를 사용해요. 즉 CrewAI가 끌어오는 전이(transitive) 의존성은 3일 이내에 릴리스된 패키지로는 resolve되지 않아요. 여러분의 직접 의존성은 이 정책에 영향을 받지 않아요. 전이 의존성이 뒤처진 걸 발견하면, 프로젝트 의존성에서 원하는 버전을 명시적으로 고정하면 돼요.
crew를 실행하려면 프로젝트 루트에서 다음을 실행하세요:
```
crewai run
```

엔터프라이즈 설치 옵션

팀과 조직을 위해 CrewAI는 설정 복잡성을 없애는 엔터프라이즈 배포 옵션을 제공해요.

CrewAI AMP (SaaS)

설치 zero — app.crewai.com에서 무료로 가입만 하면 돼요.
자동 업데이트와 유지보수
관리형 인프라와 스케일링
코드 없이(No Code) Crews 구축

CrewAI Factory (Self-hosted)

여러분 인프라를 위한 컨테이너화 배포
온프레미스를 포함한 모든 하이퍼스케일러 지원
기존 보안 시스템과의 통합

Next Steps (다음 단계)

Quickstart: Flow + agent — 퀵스타트를 따라 Flow를 만들고, 에이전트 1개짜리 crew를 실행하고, 리포트를 만들어보세요.
Join the Community — 다른 개발자들과 소통하고, 도움을 받고, 경험을 공유하세요.

더 알아보기 (Learn more)

Introduction