👥
CrewAI 치트시트

CrewAI 최신 기준 초보자 완벽 가이드: 필수 사전 설치 요건, 에이전트(Agent)·작업(Task)·크루(Crew) 3대 핵심 개념, 역할 기반 멀티 에이전트 협업, 순차 및 계층적(Hierarchical) 프로세스, 커스텀 도구 정의, 메모리 시스템 및 로컬 Ollama 연동 실전 가이드
#crewai#agent#multi-agent#llm#python#task#crew#role-playing#ollama#openai#langchain최종 업데이트: 2026-10-06
CrewAI 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 개발 환경 구성 (Prerequisites)

CrewAI는 여러 전문 AI 에이전트들이 사람처럼 역할을 분담하고 협업하는 멀티 에이전트 프레임워크입니다. 초보자도 문제없이 따라 할 수 있도록 필수 사전 환경 구성부터 시작합니다.

### 🐍 1. Python 버전 & 가상환경 (Virtual Environment)
CrewAI는 **Python 3.10 ~ 3.13 (권장: Python 3.11 또는 3.12)** 환경을 지원합니다. 패키지 버전 충돌을 방지하기 위해 가상환경 생성이 **필수**입니다.

```bash
# 1. 표준 venv 가상환경 생성
python -m venv .venv

# 2. 가상환경 활성화 (Windows PowerShell)
# ※ 권한 오류 발생 시 관리자 모드 또는: Set-ExecutionPolicy Unrestricted -Scope Process
.venv\Scripts\Activate.ps1

# 가상환경 활성화 (macOS / Linux / WSL)
source .venv/bin/activate

# 3. 또는 차세대 초고속 패키지 관리자 uv 사용 시 (강력 추천)
pip install uv
uv venv
# Windows: .venv\Scripts\activate / macOS: source .venv/bin/activate
uv pip install crewai crewai-tools
```

### 🛠️ 2. OS별 C/C++ 네이티브 빌드 도구 (컴파일러)
CrewAI의 내부 임베딩 및 벡터 저장소(ChromaDB), 토크나이저 바인딩 설치 에러를 방지하기 위해 네이티브 컴파일러가 필요합니다.
- **Windows**: [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) ("C++를 사용한 데스크톱 개발" 워크로드 체크)
- **macOS**: `xcode-select --install`
- **Linux (Ubuntu/Debian)**: `sudo apt update && sudo apt install -y build-essential python3-dev`

### 📦 3. 패키지 설치
```bash
# CrewAI 핵심 라이브러리 및 공식 도구 모음(crewai-tools) 설치
pip install crewai crewai-tools

# 환경변수 로더 및 Pydantic 데이터 검증
pip install python-dotenv pydantic
```

### 🔑 4. 환경 변수 설정 (`.env`)
프로젝트 폴더 루트에 `.env` 파일을 만들고 API 키를 설정합니다:
```bash
# OpenAI API 키 (기본 모델: gpt-4o 또는 gpt-4o-mini)
OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"

# Serper API 키 (인터넷 실시간 구글 검색 도구 사용 시 무료 발급: serper.dev)
SERPER_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

파이썬 코드 첫 줄에서 환경변수를 로드합니다:
```python
from dotenv import load_dotenv
load_dotenv()
```

---

## 2. CrewAI 핵심 개념 & 멘탈 모델 (Mental Model)

CrewAI는 실제 기업의 **프로젝트 팀**과 동일한 구조로 동작합니다.

```text
[CrewAI 아키텍처 멘탈 모델]
┌────────────────────────────────────────────────────────┐
│                      Crew (팀 전체)                     │
│  - Process.sequential (순차 진행) 또는 hierarchical (계층) │
├──────────────────────────┬─────────────────────────────┤
│   Agent (전문가 역할)     │      Task (담당 업무)       │
│  - Role (직책/역할)       │  - Description (작업 설명)  │
│  - Goal (달성 목표)       │  - Expected Output (결과물) │
│  - Backstory (배경 스토리)│  - Agent (담당자 배정)      │
│  - Tools (보유 도구)      │  - Output Pydantic (구조화) │
└──────────────────────────┴─────────────────────────────┘
```

### 🔑 3대 핵심 객체
1. **Agent (에이전트)**: "누가 하는가?" 직책(Role), 목표(Goal), 페르소나(Backstory), 보유 도구(Tools)를 가진 전문가.
2. **Task (작업)**: "무엇을 하는가?" 구체적인 작업 지침(Description)과 기대하는 결과물(Expected Output).
3. **Crew (크루)**: 에이전트와 작업을 모아 워크플로우(Process)에 따라 실행을 지휘하는 관리자.

---

## 3. [초보자 1단계] 헬로월드: 단일 에이전트 & 단일 작업

가장 단순한 1인 에이전트로 시작하여 동작 원리를 익힙니다.

```python
from crewai import Agent, Task, Crew
from dotenv import load_dotenv

# 1. 환경변수(.env) 로드
load_dotenv()

# 2. 에이전트 정의 (기술 블로그 전문 작가)
tech_writer = Agent(
    role="시니어 테크 라이터",
    goal="복잡한 최신 IT 기술을 비전공자도 이해하기 쉬운 비유로 설명하기",
    backstory="당신은 10년간 기술 블로그를 운영한 베테랑 개발자이자 작가입니다. 명쾌하고 친절한 글솜씨로 유명합니다.",
    verbose=True # 에이전트의 실시간 생각과 추론 과정을 콘솔에 출력
)

# 3. 작업 정의
writing_task = Task(
    description="{topic} 기술이 무엇인지 초등학생도 이해할 수 있는 일상생활 비유 1가지를 들어 3문장으로 설명해주세요.",
    expected_output="비유가 포함된 친절한 3문장 한국어 설명문",
    agent=tech_writer
)

# 4. 크루 결성 및 실행
crew = Crew(
    agents=[tech_writer],
    tasks=[writing_task],
    verbose=True
)

# 5. kickoff()로 작업 시작 (동적 변수 {topic} 전달)
result = crew.kickoff(inputs={"topic": "클라우드 컴퓨팅(Cloud Computing)"})

print("\n" + "="*50)
print("🎯 [최종 결과물]:\n", result)
print("="*50)
```

---

## 4. [초보자 2단계] 2인 협업: 리서처 + 라이터 순차 파이프라인

한 에이전트의 작업 결과물이 다음 에이전트의 입력으로 자동 전달되는 `Process.sequential` 기본 협업 패턴입니다.

```text
[순차 협업 워크플로우]
[사용자 주제 입력]
      │
      ▼
[1. 시니어 리서처] ──► [최신 트렌드 & 핵심 팩트 조사]
                              │
                              ▼ (결과물 자동 전달)
[2. 콘텐츠 에디터] ──► [매력적인 블로그 아티클 최종 작성]
                              │
                              ▼
                       [최종 마크다운 글]
```

```python
from crewai import Agent, Task, Crew, Process
from dotenv import load_dotenv

load_dotenv()

# 1. 첫 번째 에이전트: IT 시장 조사 전문가
researcher = Agent(
    role="인공지능 트렌드 리서처",
    goal="{topic} 분야의 2026년 최신 기술 동향과 핵심 이슈 3가지를 발굴하기",
    backstory="방대한 글로벌 IT 뉴스와 연구 논문에서 알짜배기 트렌드만 정확하게 짚어내는 데이터 분석 전문가입니다.",
    verbose=True,
    memory=True
)

# 2. 두 번째 에이전트: 테크 전문 블로거
writer = Agent(
    role="테크 아티클 에디터",
    goal="리서처가 조사한 내용을 바탕으로 개발자 독자들의 시선을 사로잡는 마크다운 글 작성하기",
    backstory="복잡한 트렌드 자료를 읽기 편한 헤드라인과 불릿 포인트로 가공하는 데 탁월한 능력을 갖춘 전문 에디터입니다.",
    verbose=True,
    memory=True
)

# 3. 작업 1: 리서치 작업
task_research = Task(
    description="{topic} 기술의 핵심 개념과 2026년 현재 가장 주목받는 실무 활용 사례 3가지를 정리하세요.",
    expected_output="핵심 개념 요약 및 3가지 실무 사례가 정리된 불릿 포인트 리포트",
    agent=researcher
)

# 4. 작업 2: 글 작성 작업 (이전 task_research의 결과를 자동으로 참고함)
task_write = Task(
    description="리서처가 작성한 리포트를 기반으로 제목, 도입부, 본문 3개 단락, 결론이 포함된 완성된 마크다운 아티클을 작성하세요.",
    expected_output="제목(#)과 소제목(##)이 갖추어진 완성된 한국어 마크다운 기술 글",
    agent=writer
)

# 5. 크루 구성 및 실행 (순차 프로세스)
editorial_crew = Crew(
    agents=[researcher, writer],
    tasks=[task_research, task_write],
    process=Process.sequential, # 앞 작업이 끝나면 다음 작업으로 전달
    verbose=True
)

# 6. 실행
final_article = editorial_crew.kickoff(inputs={"topic": "LangChain과 CrewAI의 멀티 에이전트 생태계"})
print("\n" + "#"*50)
print(final_article)
```

---

## 5. [초보자 3단계] 커스텀 도구(Tool) 개발 & 연동

에이전트가 계산기, 웹 검색, 사내 DB 조회를 직접 수행할 수 있도록 파이썬 함수를 도구로 만드는 방법입니다.

### 🧰 `@tool` 데코레이터로 손쉽게 도구 정의하기
```python
from crewai.tools import tool
from crewai import Agent, Task, Crew

# 1. 파이썬 함수에 @tool 붙이기 (독스트링이 LLM의 도구 사용 설명서가 됨)
@tool("환율 계산 도구")
def currency_converter(usd_amount: float) -> str:
    """미국 달러(USD) 금액을 입력받아 한국 원화(KRW, 환율 1,380원 기준)로 환산합니다."""
    krw = usd_amount * 1380
    return f"{usd_amount:,.2f} USD는 약 {krw:,.0f} KRW 입니다."

@tool("할인율 적용 계산기")
def apply_discount(price: float, discount_percent: float) -> str:
    """원가와 할인율(예: 20은 20%)을 받아 할인된 최종 가격을 계산합니다."""
    discounted = price * (1 - discount_percent / 100)
    return f"정가 {price:,.0f}원에서 {discount_percent}% 할인된 가격은 {discounted:,.0f}원 입니다."

# 2. 도구를 장착한 에이전트
finance_agent = Agent(
    role="전자상거래 가격 정산 전문가",
    goal="해외 직구 상품의 관세 및 원화 환산 가격을 정확히 계산하기",
    backstory="숫자에 오차가 없도록 도구를 적극적으로 활용하여 정확한 최종 청구 금액을 산출하는 회계 전문가입니다.",
    tools=[currency_converter, apply_discount], # 도구 목록 바인딩
    verbose=True
)

# 3. 작업 생성
calc_task = Task(
    description="미화 $250달러짜리 스마트워치가 15% 블랙프라이데이 세일 중입니다. 할인된 최종 원화(KRW) 금액이 얼마인지 계산 도구를 사용하여 산출하세요.",
    expected_output="할인 전후 달러 가격과 최종 계산된 원화(KRW) 금액 명시",
    agent=finance_agent
)

# 4. 실행
crew = Crew(agents=[finance_agent], tasks=[calc_task], verbose=True)
result = crew.kickoff()
print("\n결과:", result)
```

---

## 6. 계층적 프로세스 (Hierarchical Process & Manager Agent)

작업 순서를 하드코딩하지 않고, **총괄 매니저(Manager LLM)**가 팀원 에이전트들에게 일을 스스로 위임(Delegation)하고 결과를 취합하여 최종 납품하는 엔터프라이즈 패턴입니다.

```python
from crewai import Agent, Task, Crew, Process
from langchain_openai import ChatOpenAI

# 1. 실무 작업자 에이전트들
market_analyst = Agent(
    role="시장 점유율 분석가",
    goal="경쟁사 제품의 장단점 및 시장 반응 조사",
    backstory="정량적 데이터 분석을 전문으로 하는 시장 분석가입니다.",
    verbose=True
)

marketing_strategist = Agent(
    role="마케팅 전략 수립가",
    goal="신제품 런칭을 위한 효과적인 바이럴 캠페인 전략 수립",
    backstory="소비자의 심리를 꿰뚫어 보는 창의적인 마케팅 디렉터입니다.",
    verbose=True
)

# 2. 매니저 에이전트용 LLM 지정
manager_llm = ChatOpenAI(model="gpt-4o", temperature=0.2)

# 3. 최종 목표 작업
launch_task = Task(
    description="{product_name} 신제품 출시를 위한 1) 경쟁사 분석과 2) 차별화 마케팅 액션 플랜을 종합 수립하세요.",
    expected_output="경쟁 분석 및 구체적 마케팅 실행 방안이 포함된 1페이지 종합 기획서"
)

# 4. 계층적 크루 (manager_llm이 알아서 두 에이전트에게 일을 쪼개어 분배함)
project_crew = Crew(
    agents=[market_analyst, marketing_strategist],
    tasks=[launch_task],
    process=Process.hierarchical, # 🚀 계층적 자율 위임 모드
    manager_llm=manager_llm,
    verbose=True
)

result = project_crew.kickoff(inputs={"product_name": "AI 기반 자동 분리수거 로봇"})
print(result)
```

---

## 7. 구조화된 출력 (Pydantic Output)

에이전트의 결과물을 파싱하기 힘든 줄글 대신 **Pydantic 스키마**를 통해 100% 정형화된 JSON 데이터로 안전하게 추출합니다.

```python
from pydantic import BaseModel, Field
from typing import List
from crewai import Agent, Task, Crew

# 1. Pydantic 출력 스키마 정의
class JobOpening(BaseModel):
    title: str = Field(description="채용 공고 제목")
    required_skills: List[str] = Field(description="필수 요구 기술 스택 3가지 이상")
    experience_years: int = Field(description="최소 요구 경력 연수")
    summary: str = Field(description="직무 핵심 요약 1문장")

# 2. 인사 담당 에이전트
recruiter = Agent(
    role="HR 채용 전문가",
    goal="직무 기술서를 분석하여 표준 채용 규격으로 정형화하기",
    backstory="수천 건의 이력서와 직무 기술서를 분석해온 인사 베테랑입니다.",
    verbose=True
)

# 3. output_pydantic 파라미터 적용
struct_task = Task(
    description="시니어 풀스택 개발자(React, Python FastAPI, Docker 경험 5년 이상) 채용 공고를 분석하여 데이터 모델에 맞게 추출하세요.",
    expected_output="JobOpening Pydantic 규격에 부합하는 정형 데이터",
    agent=recruiter,
    output_pydantic=JobOpening # 🚀 자동 Pydantic 인스턴스화
)

crew = Crew(agents=[recruiter], tasks=[struct_task], verbose=True)
result = crew.kickoff()

# 4. Pydantic 객체로 바로 접근 가능
parsed: JobOpening = result.pydantic
print(f"직무명: {parsed.title}")
print(f"경력 요구: {parsed.experience_years}년")
print(f"필수 스킬: {', '.join(parsed.required_skills)}")
print(f"요약: {parsed.summary}")
```

---

## 8. 로컬 무료 오프라인 LLM (Ollama) 연동

OpenAI API 비용 지출 없이 내 PC의 GPU/CPU에서 완전 무료로 동작하도록 Ollama를 연결하는 방법입니다.

```python
from crewai import Agent, Task, Crew, LLM

# 1. Ollama 로컬 LLM 객체 생성 (CrewAI 전용 LLM 클래스 사용)
local_llm = LLM(
    model="ollama/llama3.2:latest",
    base_url="http://localhost:11434"
)

# 2. 로컬 모델을 탑재한 에이전트
local_coder = Agent(
    role="파이썬 백엔드 개발자",
    goal="최적화된 파이썬 함수와 유닛테스트 코드 작성",
    backstory="오프라인 보안 환경에서도 최고의 코드를 생산하는 클린 코드 전문가입니다.",
    llm=local_llm, # 🚀 로컬 LLM 지정
    verbose=True
)

# 3. 작업
code_task = Task(
    description="이메일 주소 유효성을 검사하는 정규식 함수 `validate_email(email: str) -> bool`을 작성하세요.",
    expected_output="설명 주석이 포함된 파이썬 함수 코드 블록",
    agent=local_coder
)

crew = Crew(agents=[local_coder], tasks=[code_task], verbose=True)
print(crew.kickoff())
```

---

## 9. 실무 개발자 체크리스트 & 트러블슈팅

| 문제 상황 | 원인 | 해결 방법 (Best Practice) |
| :--- | :--- | :--- |
| **에이전트가 무한 루프에 빠짐** | 도구 호출 실패를 반복하거나 목표가 모호함 | Agent에 `max_iter=5` 설정 및 Task description에 명확한 종료 조건 명시 |
| **다른 에이전트에게 엉뚱한 질문 반복** | 에이전트 간 위임 권한이 과도하게 켜져 있음 | 불필요한 위임을 막으려면 Agent에 `allow_delegation=False` 명시 |
| **OpenAI Rate Limit 초과 (429 에러)** | 에이전트들이 단시간에 너무 많은 요청 발생 | Crew 생성 시 `max_rpm=20` (분당 최대 요청 수) 설정 |
| **메모리(Memory) 활성화 오류** | 임베딩 모델 미설정 또는 chromadb 누락 | `pip install chromadb` 설치 확인 및 OpenAI 임베딩 키 설정 |
| **비용 절감 최적화** | 모든 에이전트에 최고급 모델(GPT-4o) 배정 | 단순 작성/조사 에이전트는 `gpt-4o-mini`, 최종 매니저만 `gpt-4o`로 분리 |
💬
CrewAI 치트시트

의견 및 질문

댓글 수정

댓글 삭제
