AI 에이전트가 혼자가 아니라 '팀'으로 일한다면? CrewAI는 역할·목표·배경 스토리를 가진 에이전트들이 실제 조직처럼 협업하는 프레임워크다. PwC의 코드 생성 정확도 700% 개선부터 일일 1,200만 실행까지 — 핵심 개념, 실전 패턴, 프로덕션 노하우를 총정리한다.
AI 에이전트 하나가 모든 것을 잘하기를 기대하는 것은, 한 사람에게 리서치·글쓰기·데이터 분석·디자인을 전부 맡기는 것과 같다. 가능은 하지만 최적은 아니다.
현실의 조직은 다르게 작동한다. 리서처가 조사하고, 분석가가 데이터를 정리하고, 작가가 보고서를 쓴다. 각자의 전문 역할이 있고, 명확한 업무가 할당되며, 팀으로 협업한다.
CrewAI는 이 조직 구조를 AI 에이전트에 그대로 적용한 프레임워크다.
researcher = Agent(role="시니어 리서처", goal="최신 AI 트렌드 조사")
analyst = Agent(role="데이터 분석가", goal="리서치 결과를 수치로 분석")
writer = Agent(role="테크니컬 라이터", goal="분석 결과를 보고서로 작성")
에이전트에게 역할(role), 목표(goal), **배경 스토리(backstory)**를 부여하는 것 — 이것이 CrewAI의 핵심 아이디어다. 코드를 읽기만 해도 "이 팀이 뭘 하는 건지" 직관적으로 이해된다.
2023년 11월 GitHub에 공개된 이후, 46,500+ 스타, 일일 1,200만 에이전트 실행, Fortune 500 기업의 60%가 사용 — CrewAI는 가장 빠르게 성장한 AI 에이전트 프레임워크가 되었다.
Joao(Joe) Moura, 소프트웨어 업계 20년 경력의 엔지니어링 리더. 마케팅 데이터 플랫폼 Clearbit에서 AI 엔지니어링 디렉터로 일하던 중, AI 에이전트 오케스트레이션 코드를 매 프로젝트마다 처음부터 작성하는 비효율에 불만을 느꼈다.
그가 만든 초기 프로토타입은 LinkedIn 콘텐츠 자동 생성 시스템이었다. 이 시스템은 일일 약 600건의 인바운드 리드를 생성하며 가치를 증명했고, 이 경험이 CrewAI 프레임워크의 토대가 되었다.
| 시점 | 마일스톤 |
|---|---|
| 2023.11 | GitHub 오픈소스 공개, 빠른 커뮤니티 성장 |
| 2024.01 | 회사 설립 (Moura CEO + Rob Bailey COO) |
| 2024.09 | LangChain 의존성 완전 제거 — 독립 프레임워크로 전환 |
| 2024.10 | Flows 기능 도입, Series A $18M 펀딩 (Insight Partners) |
| 2025.10 | v1.0 GA — 프로덕션 성숙도 달성 |
| 2025.11 | MCP(Model Context Protocol) 1급 지원 |
| 2026.03 | v1.11.0 (현재), 일일 1,200만 실행 |
특히 LangChain 독립(2024.09)이 중요한 전환점이었다. Moura는 직접 "LangChain is completely removed from CrewAI"라고 발표했다. 처음부터 자체 설계한 경량 엔진으로 교체하여, 의존성 문제와 성능 오버헤드를 해결했다.
CrewAI의 모든 개념은 실제 조직 구조의 은유다.
에이전트에는 세 가지 핵심 속성이 있다:
from crewai import Agent
researcher = Agent(
role="AI 트렌드 시니어 리서처", # 역할
goal="2026년 AI 에이전트 생태계의 최신 동향을 조사", # 목표
backstory="""당신은 10년 경력의 AI 기술 리서처입니다.
학술 논문과 업계 보고서를 분석하여 핵심 트렌드를
도출하는 데 탁월합니다.""", # 배경 스토리
tools=[SerperDevTool()], # 사용 가능한 도구
verbose=True
)
backstory가 왜 중요한가? backstory는 에이전트의 성격과 전문성을 LLM에 주입한다. "10년 경력의 리서처"라는 backstory를 가진 에이전트는 단순 검색이 아니라 분석적 시각으로 정보를 다룬다. 실제로 backstory의 품질이 에이전트 출력 품질에 직접적으로 영향을 미친다.
from crewai import Task
research_task = Task(
description="2026년 AI 에이전트 프레임워크의 최신 동향을 조사하세요. "
"주요 프레임워크의 특징, 채택률, 트렌드를 포함하세요.",
expected_output="10개 항목의 핵심 발견사항 목록 (마크다운 형식)",
agent=researcher,
tools=[SerperDevTool()]
)
expected_output이 핵심이다. 이것은 에이전트에게 **"어떤 형태의 결과물을 내야 하는지"**를 명확히 알려준다. 모호한 expected_output은 모호한 결과를 만든다.
from crewai import Crew, Process
crew = Crew(
agents=[researcher, analyst, writer],
tasks=[research_task, analysis_task, report_task],
process=Process.sequential, # 순차 실행
memory=True, # 크루 간 기억 공유
verbose=True
)
result = crew.kickoff(inputs={"topic": "AI Agents 2026"})
실전 팁: 대부분의 경우 Sequential이면 충분하다. Hierarchical은 매니저의 매 판단마다 LLM 호출이 추가되어 비용이 급증한다. 명확한 태스크 순서를 알고 있다면 Sequential을 쓰고, "어떤 에이전트에게 맡길지 모르겠다"는 경우에만 Hierarchical을 고려하라.
CrewAI의 차별화된 설계 — 에이전트와 태스크 정의를 YAML 파일로 분리한다.
{topic}은 동적 변수다. crew.kickoff(inputs={"topic": "AI Agents"})를 호출하면 자동으로 대체된다. 같은 크루를 다른 주제에 재사용할 수 있다.
이 설계의 장점:
Crew만으로는 분기, 조건부 실행, 외부 시스템 연동이 어렵다. "검색 결과가 부족하면 다른 소스를 시도"하거나, "사람의 승인을 받은 후 다음 단계 진행" 같은 흐름은 순차/위계 프로세스로 표현하기 어렵다.
2024년 10월 도입된 Flows는 Crew 위에 결정론적 제어 계층을 추가한다. Crew가 "자율적 에이전트 팀"이라면, Flow는 "팀을 관리하는 프로세스"다.
from crewai.flow.flow import Flow, listen, start, router
from pydantic import BaseModel
class ReportState(BaseModel):
topic: str = ""
research: str = ""
report: str = ""
approved: bool = False
class ReportFlow(Flow[ReportState]):
@start()
def gather_topic(self):
self.state.topic = "AI Agents 2026"
@listen(gather_topic)
def do_research(self):
# Crew에 리서치 위임
result = ResearchCrew().crew().kickoff(
inputs={"topic": self.state.topic}
)
self.state.research = result.raw
@router(do_research)
def check_quality(self):
if len(self.state.research) > 1000:
return "write_report"
return "do_research" # 다시 리서치
@listen("write_report")
def write_report(self):
result = WritingCrew().crew().kickoff(
inputs={"research": self.state.research}
)
self.state.report = result.raw
핵심 데코레이터:
@start() — 진입점 (여러 개 → 병렬 실행)@listen(func) — func 완료 후 트리거@router(func) — 조건부 라우팅 (문자열 반환)프로덕션 아키텍처 권장 패턴: Flow-first — 항상 Flow로 시작하고, 복잡한 자율적 작업만 Crew에 위임한다.
2025년 11월부터 CrewAI는 **MCP(Model Context Protocol)**를 1급으로 지원한다. MCP 서버에 연결하면 에이전트가 외부 도구를 자동으로 발견하고 사용할 수 있다.
agent = Agent(
role="데이터 분석가",
mcps=[
"https://mcp.exa.ai/mcp?api_key=KEY", # 웹 검색
"snowflake", # 데이터베이스
"stripe#list_invoices" # 특정 도구만
]
)
URL, 이름, 또는 이름#도구명 형식으로 간단하게 연결한다. Stdio, SSE, HTTPS 전송 모두 지원. A2A(Agent-to-Agent) 프로토콜도 지원하여, 다른 프레임워크(LangGraph, Google ADK 등)의 에이전트와 상호 운용이 가능하다.
글로벌 컨설팅 기업 PwC는 자사 Agent OS의 핵심에 CrewAI를 채택했다. 코드 생성 정확도가 **10% → 70%**로 향상 — 700% 이상의 개선이다. 멀티에이전트 리뷰·검증 루프가 단일 에이전트에서 불가능했던 자기 수정을 가능하게 했다.
NVIDIA는 CrewAI와 NVIDIA AI Enterprise를 통합하여 프로덕션급 멀티에이전트 시스템을 구축했다. NemoClaw는 에이전트가 스스로 도구를 발견하고 워크플로를 진화시키는 시스템이다.
IBM은 watsonx.ai와 CrewAI 멀티에이전트 오케스트레이션을 통합하여 엔터프라이즈 AI 워크플로를 강화했다.
전문화하라. "Research Agent" 같은 범용 에이전트 대신 "SaaS 시장 분석 전문가" 같은 구체적 역할을 부여한다. 범용 에이전트는 컨텍스트 윈도우가 폭발하고, 도구 선택에서 혼란을 일으킨다.
도구를 과다 할당하지 마라. 에이전트에 10개 이상의 도구를 주면 LLM이 어떤 도구를 써야 할지 혼동한다. 3~5개가 적정선이다.
backstory를 진지하게 작성하라. "당신은 훌륭한 분석가입니다"는 약하다. "당신은 McKinsey에서 10년간 근무한 전략 컨설턴트로, 특히 B2B SaaS 시장의 경쟁 분석에 전문성이 있습니다. 데이터 기반 의사결정을 선호하며, 항상 출처를 명시합니다."가 더 효과적이다.
expected_output을 명확하게. "좋은 보고서"가 아니라 "10개 항목의 마크다운 불릿 리스트, 각 항목에 출처 URL 포함"처럼 구체적으로 정의한다.
context로 의존성을 명시하라. 태스크 B가 태스크 A의 결과를 필요로 하면 context=[task_a]로 명시한다. 이것이 태스크 간 "계약(contract)"이다.
구조화된 출력을 강제하라. output_pydantic으로 Pydantic 모델을 지정하면, 에이전트가 반드시 해당 스키마를 따르는 출력을 생성한다. 파이프라인 안정성에 필수적이다.
from pydantic import BaseModel
class ResearchOutput(BaseModel):
findings: list[str]
sources: list[str]
confidence: float
task = Task(
description="...",
expected_output="구조화된 리서치 결과",
output_pydantic=ResearchOutput,
agent=researcher
)
Guardrails로 출력을 검증하라. v1.x부터 태스크에 guardrail 함수를 붙여 출력을 자동 검증할 수 있다. 검증 실패 시 에이전트가 다시 시도한다.
무한 루프를 경계하라. 에이전트가 태스크를 완료하지 못하고 반복 실행하는 "둠 루프"가 발생할 수 있다. max_iter와 타임아웃을 반드시 설정한다.
할루시네이션을 모니터링하라. 에이전트가 도구를 사용하지 않고 결과를 "날조"하는 경우가 있다. verbose 로그를 확인하고, 프로덕션에서는 CrewAI Tracing을 활성화한다.
Sequential을 기본으로. Hierarchical 프로세스는 매니저의 매 결정에 LLM 호출이 추가되어 비용이 2~3배 증가한다.
비핵심 에이전트에는 저렴한 모델을. 리서치 에이전트에 GPT-4o, 분류·요약 에이전트에는 GPT-4o-mini를 할당한다.
analyst = Agent(
role="데이터 분류기",
llm="gpt-4o-mini", # 저렴한 모델로 충분
...
)
CrewAI의 가장 큰 약점 중 하나가 단위 테스트의 어려움이다. 전체 크루를 돌리지 않으면 개별 에이전트/태스크를 테스트하기 어렵다.
실전 우회법:
output_pydantic으로 출력 스키마를 강제하고, 스키마 준수를 검증crewai test CLI로 자동화된 회귀 테스트 실행이 질문은 가장 자주 나오는 질문이다. 답은 명확하다:
| 기준 | CrewAI | LangGraph |
|---|---|---|
| 핵심 모델 | 역할 기반 팀 | 그래프 상태 머신 |
| 학습 곡선 | 수 시간 (가장 쉬움) | 1~2주 (가장 어려움) |
| 프로토타이핑 | 가장 빠름 | 셋업 오버헤드 |
| 복잡한 분기/루프 | 제한적 (Flows로 보완) | 최강 |
| 디버깅 | verbose 로그 | LangSmith (최강) |
| 프로덕션 확장 | 좋음 | 매우 좋음 |
복잡한 그래프 워크플로: 임의의 순환·분기를 표현하는 데는 LangGraph가 더 유연하다. CrewAI의 Flows가 이를 보완하지만, 여전히 LangGraph만큼의 자유도는 없다.
소형 모델 호환성: 7B 파라미터급 오픈소스 모델에서는 도구 호출이 제대로 작동하지 않는 경우가 많다. GPT-4o급 이상의 모델을 권장한다.
단위 테스트 어려움: 크루를 부분적으로 테스트하기 어렵다는 것이 커뮤니티에서 가장 자주 제기되는 비판이다.
에이전트 비준수: 에이전트가 태스크를 건너뛰거나 도구를 사용하지 않고 결과를 날조할 수 있다. Guardrails와 모니터링이 필수적이다.
Python 전용: 다양한 기술 스택을 사용하는 조직에서는 제한이 될 수 있다.
pip install crewai
crewai create crew my-first-crew
cd my-first-crew
이 명령으로 YAML 기반 프로젝트 구조가 자동 생성된다:
my-first-crew/
├── src/my_first_crew/
│ ├── config/
│ │ ├── agents.yaml # 에이전트 정의
│ │ └── tasks.yaml # 태스크 정의
│ ├── crew.py # 크루 조립
│ └── main.py # 진입점
└── pyproject.toml
agents.yaml과 tasks.yaml을 수정한 뒤:
crewai run
1단계: 공식 Quickstart — 15분이면 첫 크루 완성
2단계: DeepLearning.AI: Multi AI Agent Systems — Joao Moura 직접 강의, 무료
3단계: Practical Multi AI Agents — 고급 패턴
4단계: 공식 문서 Concepts 섹션 — Flows, Memory, Knowledge 심화
CrewAI의 핵심 가치는 한 문장이다:
AI 에이전트를 실제 팀처럼 조직하는 가장 직관적이고 빠른 방법을 제공한다.
역할, 목표, 배경 스토리 — 이 세 가지로 에이전트를 정의하는 것은 인간이 팀을 구성하는 방식과 동일하다. YAML로 설정을 분리하여 비개발자도 에이전트를 이해할 수 있게 한 것, Flows로 결정론적 제어를 추가한 것, MCP로 외부 세계와 연결한 것 — 모두 이 핵심 가치를 확장한다.
LangGraph가 "복잡한 워크플로를 정밀하게 제어하는" 도구라면, CrewAI는 "빠르게 팀을 꾸려 결과를 내는" 도구다. 둘은 경쟁이라기보다 보완 관계이며, 프로젝트의 성격에 따라 적절한 선택이 달라진다.
PwC, NVIDIA, IBM이 선택한 이유는 복잡한 기능이 아니라, "팀원에게 역할을 주고 일을 시키는" 인간의 직관에 가장 가까운 인터페이스를 제공하기 때문이다.
참고 자료