프레임워크

CrewAI 실전: 멀티 Agent 협력을 '블록 쌓기'처럼 만든 프레임워크

GitHub Star 5.7만 개의 멀티 Agent 오케스트레이션 프레임워크 CrewAI. 역할 분담과 태스크 체인만으로 복잡한 협력을 수십 줄 코드로 단순화한다. 핵심 추상화, Process 메커니즘, 그리고 LangGraph·AutoGen과의 차이를 정리한다.

글자 크기

GitHub에서 Star 5.7만 개를 기록한 crewAIInc/crewAI는 꽤 흥미로운 프로젝트다. 상태机的 작성법을 알려주지도 않고, 대화에 대한 철학을 설교하지도 않는다. 대신 멀티 Agent 협력을 세 가지 개념으로 압축한다. Agent(역할이 부여된 LLM 호출 단위), Task(의존성을 가진 작업), Crew(팀). 여기에 Process 파라미터 하나로 실행 방식을 결정한다. 프레임워크 전체의 체감은 프로그램을 짜는 것보다 설정 파일을 쓰는 것에 가깝다.

해결하려는 문제

단일 Agent가 긴 체인 태스크에서 부딪히는 벽은 세 가지다.

  • 컨텍스트 윈도우 폭발: 리서치-분석-작성과 같은 흐름을 하나의 prompt에 욱여넣으면 토큰이 터진다.
  • 계획 능력 붕괴: 복잡한 태스크를 분해하라 하면 LLM이 단계를 건너뛴다.
  • 도구 호출 혼란: 검색, 계산, 파일 작성을 한꺼번에 던지면 하나만 실패해도 전체가 무너진다.

AutoGen은 대화식에 가깝고, Agent 간 협력이 chat history로 끌려가며 제어 단위가 거칠다. LangGraph는 그래프 형태로 유연하지만 상태机을 그리는 법을 먼저 익혀야 한다. CrewAI는 중간 지점을 택했다. 역할 분담과 태스크 체인을 Python 또는 YAML로 선언만 하면 돌아간다. 본질적으로 멀티 Agent 협력을 "상태机 작성"에서 "YAML 설정" 수준으로 끌어내린 셈이다.

사용법

pip install crewai로 설치하고, OpenAI 또는 Anthropic API Key를 준비한다. 아래는 최소 예시다. Researcher와 Writer를 정의해 블로그 글 하나로 연결한다.

from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool
import os

os.environ["OPENAI_API_KEY"] = "your-key"
os.environ["SERPER_API_KEY"] = "your-serper-key"

search_tool = SerperDevTool()

researcher = Agent(
    role="연구원",
    goal="특정 주제의 최신 산업 데이터를 수집",
    backstory="당신은 공개 자료에서 핵심 숫자를 추출하는 데 능한资深 산업 애널리스트다",
    tools=[search_tool],
    verbose=True
)

writer = Agent(
    role="작가",
    goal="데이터를 500자 분량의 짧은 보고서로 작성",
    backstory="당신은 간결하고 결론 우선 스타일의 테크 미디어 에디터다",
    verbose=True
)

task1 = Task(
    description="2024년 중국 AI Agent 산업의 펀딩 데이터를 검색",
    expected_output="핵심 펀딩 이벤트 5건, 각 항목에 회사명·금액·투자자 포함",
    agent=researcher
)

task2 = Task(
    description="위 데이터를 기반으로 500자 산업 단평을 작성",
    expected_output="데이터 인용을 포함한 구조적인 중국어 단평",
    agent=writer,
    context=[task1]
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[task1, task2],
    process=Process.sequential
)

result = crew.kickoff()
print(result)

실행하면 Researcher가 먼저 검색 도구를 호출하고, 그 결과를 Writer에게 넘긴다. context=[task1] 한 줄이 핵심이다. 상위 Task의 출력이 자동으로 하위 Agent의 컨텍스트에 주입되므로 직접 관리할 필요가 없다. 전체 흐름이 Python 32줄로 끝난다.

동작 원리

핵심 추상화는 네 계층이다.

1. Agent: role + goal + backstory + tools + llm. "인격"이 부여된 LLM 호출 단위다. backstory는 단순한 데코레이션이 아니라 system prompt에 그대로 합쳐져 Agent의 행동 스타일에 영향을 준다.

2. Task: description + expected_output + agent + context. context는 의존하는 상위 Task 목록이며, 해당 Task들의 출력이 본 Task의 prompt에 주입된다. 태스크 결과는 context 필드를 통해 자동으로 전달된다.

3. Crew: Agent와 Task를 묶고, Process로 실행 방식을 결정한다.

4. Process: 세 가지 모드를 제공한다.

  • sequential: 순차 실행. 가장 흔히 쓰인다.
  • hierarchical: Manager Agent를 동적으로 생성해 위임한다. "감독-실행" 두 층 구조가 프레임워크에 내장된 셈이다.
  • async: 병렬/비동기 트리거.

hierarchical 모드만 따로 짚을 가치가 있다. 실행 시점에 Manager LLM이 동적으로 spawn되며, 어떤 Task를 어떤 Agent에 언제 할당할지 그 Manager가 결정한다. 즉 CrewAI가 "프로젝트 매니지먼트" 로직을 프레임워크 안에 박아둔 것이다. 스위치 하나만 켜면 되므로 스케줄링을 직접 구현할 필요가 없다. 다만 대가가 명확하다. LLM 호출이 한 번 더 발생해 토큰 비용이 거의 두 배가 된다. 가벼운 태스크에 켜는 건 금물이다.

장점과 단점

장점

  • YAML과 Python을 모두 지원해 상태机에 익숙하지 않은 개발자도 진입 장벽이 낮다.
  • Star 5.7만 개에 걸맞게 커뮤니티가 활발하고 issue 응답도 빠르다.
  • hierarchical 모드를 그대로 쓸 수 있어 스케줄링 로직을 직접 짤 필요가 없다.

단점

  • 중국산 모델을 쓰려면 LLM wrapper를 직접 작성해야 하며, 공식 문서 지원이 얇다.
  • 긴 태스크 체인에서 컨텍스트 전달 경로가 불투명해 디버깅이 피곤하다.
  • LangGraph에 비해 그래프 제어와 조건 분기가 약해, 복잡한 비즈니스 로직은 Process 세 가지 모드에 갇혀버린다.
  • 도구 호출 자체는 지원하지만 Function Calling의 에러 처리가 거칠다.

가로로 비교하면 이렇다. LangGraph는 유연하지만 그래프를 직접 그려야 하고, AutoGen은 대화식이라 태스크 경계가 모호하다. CrewAI는 그 사이로, 체감은 블록 쌓기에 가깝지만 천장이 낮다.

직접 돌려본 결과

세 Agent 시나리오를 구성해 돌렸다. Researcher가 자료를 찾고 → Analyst가 데이터를 정리하고 → Writer가 보고서를 쓰는 구조, sequential 모드, 모델은 전부 gpt-4o-mini.

측정 결과는 다음과 같다.

  • 시작부터 첫 출력까지 약 12초(LLM 호출 3회 포함).
  • 총 토큰 소비 약 4500 tokens(도구 호출 제외).
  • 코드량 Python 32줄.

단일 Agent에 "검색-분석-보고서 작성"을 한 번에 시키는 방식과 비교하면, 단일 Agent는 코드가 단 8줄에 불과했지만 출력 품질이 눈에 띄게 떨어졌다. 분석 단계가 자주 생략되고, writer 단계에서 데이터를 잘못 인용했다. 멀티 Agent의 분리가 품질 차이를 만들었다. 단, LLM이 충분히 강력하다는 전제가 붙는다.

주요 시행착오

  • hierarchical 모드는 Manager Agent가 LLM 호출을 한 번 더 잡아먹어 토큰 비용이 거의 두 배가 된다.
  • verbose=True의 기본 출력이 상당히 장황하므로 프로덕션에서는 반드시 꺼야 한다.
  • 도구 호출 실패 시 CrewAI의 재시도 메커니즘이 약하다. 바깥에 한 겹의 에러 핸들링을 직접 감싸는 편이 낫다.

이런 사용자에게 추천

적합한 경우

  • 멀티 Agent Demo/POC를 빠르게 만들고 싶은 팀.
  • 업무 흐름이 자연스럽게 "분업 협업" 형태인 경우(연구-분석-작성, 요구사항-개발-테스트 등).
  • 상태机과 컨텍스트 관리를 처음부터 직접 짜고 싶지 않은 엔지니어.

부적합한 경우

  • 정교한 조건 분기와 루프 제어가 필요한 복잡한 로직(→ LangGraph).
  • 비용에 민감한 고빈도 호출 시나리오(멀티 Agent는 곧 LLM 호출 배수로 이어진다).
  • 중국산 모델 위주인 프로젝트(커스텀 LLM 어댑터 레이어를 직접 작성할 각오가 없다면).
  • 프로덕션급 긴 체인 태스크(디버깅 가시성이 부족하다).

CrewAI의 포지셔닝은 명확하다. 멀티 Agent라는 주제의 진입 장벽을 바닥까지 낮추는 것. 가장 강력한 프레임워크는 아니지만, 30분 안에 결과를 볼 수 있는 프레임워크일 가능성이 높다. "여러 Agent가 한 일을 분업한다"는 시나리오라면 시도해볼 만하고, "복잡한 조건 분기와 상태 관리"가 핵심이라면 LangGraph로 가는 편이 정답이다.


참고: crewAIInc/crewAI - GitHub

출처: https://github.com/crewAIInc/crewAI