CrewAI 실전 구성하다 막혔던 3가지, 공식 예제엔 없던 문제들

IX · FIELD NOTES

VOL.027 / AGENT-OPS
2026.05.13

 

CREWAI · PITFALLS

공식 예제엔
없던 함정
3가지.

CrewAI 실전 구성에서 반드시 만나는 메시지 누적, 컨텍스트 자동 요약, 그리고 디버깅 지옥 — 코드로 정리한 회피 패턴.

READ · 9 MIN
PYTHON · LLM · AGENTOPS

brief.ix-works.xyz
FILED UNDER · AI / IT

IX

IX Team

인터랙션 익스피리언스 · AI 에이전트 시스템 리서치

2026.05.13 · 9 MIN READ

CrewAI 실전 구성하다 막혔던 3가지, 공식 예제엔 없던 문제들

CrewAI는 멀티에이전트 오케스트레이션 라이브러리 중 가장 빠르게 성장한 축에 속한다 — GitHub 36.4k 스타 기준(2026.05). 그러나 공식 튜토리얼을 따라 만든 hello-world와 실전 파이프라인 사이엔 분명한 간극이 있다. 이 글은 그 간극에서 자주 만나는 3가지 문제와 회피 코드를 정리한다.

INFORMATION GAIN

이 글은 CrewAI 공식 문서·GitHub Issues #4319·Discord 커뮤니티 보고를 교차 검증해 정리했다. 공식 문서엔 흩어져 있거나 빠진 항목 — 특히 에이전트 인스턴스 재사용 시 메시지 누적 버그와 respect_context_window의 silent data loss는 한국어 자료에서 거의 다뤄지지 않는다.

§ 01 · PROCESS MODE

Sequential vs Hierarchical, 처음에 헷갈리는 지점

CrewAI에서 Crew를 만들 때 process 파라미터로 두 가지를 고를 수 있다. 둘은 단순 옵션 차이가 아니라 오케스트레이션 철학이 다르다.

Sequential은 말 그대로 순서대로 실행된다. 태스크 1이 끝나면 그 출력이 태스크 2의 컨텍스트로 넘어간다. 에이전트들이 각자 맡은 태스크를 차례로 처리하는 구조다. 공식 예제 대부분이 이 방식이다.

Hierarchical은 매니저 에이전트가 있다. 매니저가 전체 흐름을 보면서 다른 에이전트에게 태스크를 위임한다. 더 복잡한 오케스트레이션에 유리하다.

PROCESS.SEQUENTIAL

한 줄 파이프라인

TASK 1 → TASK 2 → TASK 3

• ▸ 출력이 다음 태스크 컨텍스트로 자동 전달
• ▸ 공식 튜토리얼 기본값
• ▸ manager 설정 불필요

PROCESS.HIERARCHICAL

매니저 위임형

MANAGER ↙ ↓ ↘

AGENT AGENT AGENT

• ▸ manager가 동적으로 태스크 분배
• ▸ 복잡한 분기·재시도에 유리
• ▸ manager_agent 또는 manager_llm 필수

FIG.01 · 두 모드의 실행 구조 차이

여기서 처음에 자주 걸리는 함정이 있다. Hierarchical을 쓰려면 manager_agent 또는 manager_llm 중 하나를 반드시 설정해야 한다. 둘 다 없으면 AttributeError가 뜬다.

# ❌ 이렇게 하면 AttributeError
crew = Crew(
    agents=[researcher, writer],
    tasks=[task],
    process=Process.hierarchical,  # manager 없음!
)

# ✅ manager_agent 또는 manager_llm 중 하나는 필수
from crewai import LLM
manager_llm = LLM(model="gpt-4o")

crew = Crew(
    agents=[researcher, writer],
    tasks=[task],
    process=Process.hierarchical,
    manager_llm=manager_llm,
)

§ 02 · PITFALL #1

같은 에이전트 재사용하면 메시지가 쌓인다

실무에서 가장 많이 만나는 문제다. Flow를 쓰면서 @listen 데코레이터로 파이프라인을 짤 때 같은 에이전트 인스턴스를 여러 태스크에 걸쳐 재사용하는 경우가 많다.

코드 중복도 줄고 자연스러운 패턴처럼 보이기 때문이다. 근데 이게 문제다. CrewAI의 _update_executor_parameters() 메서드는 에이전트를 재사용할 때 도구나 프롬프트 같은 파라미터는 업데이트하는데, self.agent_executor.messages는 안 비운다. 그래서 태스크가 반복될수록 메시지 히스토리가 누적된다.

MESSAGE BUFFER GROWTH

TASK 1 실행 후

4 msgs

 

시스템 1 · 유저 1 · 어시스턴트 2

TASK 2 실행 후

8 msgs

 

여기서 이상해지기 시작

TASK 3 실행 후

12 msgs

 

컨텍스트 폭증 · 빈 응답 발생

→ 결과: ValueError: Invalid response from LLM call - None or empty

FIG.02 · 동일 인스턴스 재사용 시 누적 버퍼 (출처: GitHub Issue #4319)

결국 컨텍스트 창이 꽉 차거나 중복된 시스템 프롬프트로 LLM이 빈 응답을 돌려보낸다. GitHub Issue #4319에 이 버그가 보고되어 있다. 해결 방법은 에이전트 인스턴스를 태스크마다 새로 만드는 것이다.

# ❌ 같은 인스턴스 재사용 (메시지 누적 위험)
researcher = Agent(role="Researcher", ...)

@listen(step1)
def step2(self, result):
    task = Task(description="...", agent=researcher)  # 같은 인스턴스!
    crew = Crew(agents=[researcher], tasks=[task])
    return crew.kickoff()

# ✅ 태스크마다 새 인스턴스 (안전)
def make_researcher():
    return Agent(role="Researcher", ...)

@listen(step1)
def step2(self, result):
    researcher = make_researcher()  # 매번 새로 생성
    task = Task(description="...", agent=researcher)
    crew = Crew(agents=[researcher], tasks=[task])
    return crew.kickoff()

§ 03 · PITFALL #2

context window 설정을 모르고 넘어가면 생기는 일

CrewAI Agent에는 respect_context_window라는 파라미터가 있다. 기본값은 True. 활성화되어 있으면 대화 히스토리가 LLM의 컨텍스트 한도에 근접하면 자동으로 요약해서 줄여준다.

처음엔 이게 편리해 보인다. 에러 없이 실행이 계속 되니까. 근데 함정이 있다. 자동 요약 과정에서 정보가 일부 손실된다. 긴 리서치 결과나 세부 데이터가 있는 태스크라면 중요한 내용이 날아갈 수 있다.

DEFAULT

respect_context_window
= True

자동 요약 모드

• + 컨텍스트 초과 자동 처리
• + 실행 중단 없음
• − silent data loss (조용한 손실)
• − 정밀 작업엔 부적합

PRECISION MODE

respect_context_window
= False

엄격 모드

• + 정보 무손실 보장
• + 한도 초과 시 에러로 중단
• + RAG 도구 연동 신호로 활용
• − 사전 컨텍스트 설계 필요

FIG.03 · 두 모드의 트레이드오프

# 기본: 컨텍스트 초과 시 자동 요약 (정보 손실 가능)
agent = Agent(
    role="Analyst",
    goal="Thorough analysis",
    backstory="...",
    respect_context_window=True,  # 기본값
)

# 정밀 작업: 컨텍스트 초과 시 에러로 중단
agent = Agent(
    role="Analyst",
    goal="Thorough analysis",
    backstory="...",
    respect_context_window=False,  # 손실 없이 중단
)

법률 문서 분석이나 코드 리뷰처럼 정확성이 중요한 케이스라면 False로 설정하는 게 낫다. 에러가 나면 컨텍스트 한도가 더 큰 모델로 전환하거나 RAG 도구를 붙이는 구조를 잡아야 한다.

§ 04 · PITFALL #3

verbose 없이 디버깅하면 막막하다

CrewAI 에이전트가 실행 중에 뭘 하고 있는지 보려면 verbose=True를 꼭 켜야 한다.

“

verbose 안 켠 멀티에이전트 디버깅은,
불 꺼진 방에서 손으로 부품 맞추기다.

— AGENTOPS · FIELD NOTE

FIG.04 · 가시성 없는 멀티에이전트는 블랙박스가 된다

안 켜면 기다리다 에러 나거나 엉뚱한 결과가 나온다. 어느 단계에서 문제가 생긴 건지 알 수가 없다.

agent = Agent(
    role="Researcher",
    goal="Find relevant information",
    backstory="Expert researcher",
    verbose=True,  # 이거 없으면 디버깅 지옥
)

crew = Crew(
    agents=[agent],
    tasks=[task],
    verbose=True,  # Crew 레벨에서도 켜두기
)

verbose 로그를 보면 에이전트가 어떤 도구를 선택했는지, 어떤 응답을 받았는지, 어디서 루프를 돌고 있는지 다 보인다. 처음 구성할 때는 무조건 켜두는 게 맞다.

또 하나, max_iter 파라미터다. 기본값이 25인데, 에이전트가 한 태스크에서 최대 몇 번 반복 추론할 수 있는지를 제한한다. 복잡한 리서치 태스크라면 높여야 할 때가 있다.

§ 05 · CHECKLIST

실전 구성 전 체크리스트

세 가지 문제를 사례로 보면서 정리해보면, 구성 시작 전에 반드시 확인해야 할 항목 5개가 나온다.

PRE-FLIGHT · 5 ITEMS

01

에이전트 인스턴스 공유 여부 점검

Flow 여러 스텝에서 같은 에이전트를 쓴다면 팩토리 함수로 감싸서 매번 새로 생성

02

Hierarchical 쓸 때 manager 설정

manager_agent 또는 manager_llm 둘 중 하나는 반드시 — 빠뜨리면 AttributeError

03

verbose=True 켜두기

개발·테스트 단계에서는 무조건 — Agent와 Crew 양쪽 모두

04

respect_context_window 값 결정

정보 손실에 민감한 도메인이면 False + RAG 조합으로 설계

05

max_iter 적정값 검토

기본 25가 적정한지 태스크 복잡도에 따라 판단 — 부족하면 무한 루프처럼 보임

FIG.05 · 실전 구성 전 자가점검 항목

마지막으로 한 가지 — CrewAI는 2024~2026년에 걸쳐 메이저 버전이 빠르게 올라간 라이브러리다. 영문 공식 문서가 아직 한국어 자료를 앞서는 영역이 많고, 버전이 바뀌면서 동작이 달라지는 경우도 있다. 에러를 만났을 때는 GitHub Issues 탭이 공식 문서보다 실시간성이 높다는 점을 기억해두면 좋다.

REFERENCES · 참고자료

• [1] CrewAI 공식 문서 — docs.crewai.com
• [2] GitHub Issue #4319 — agent_executor.messages not reset on agent reuse
• [3] CrewAI GitHub Repository — 36.4k stars (2026.05 기준)
• [4] CrewAI Discord 커뮤니티 보고 — Process.hierarchical manager 누락 사례

IX FIELD NOTES · VOL.027
FILED · AGENT-OPS / CREWAI

brief.ix-works.xyz
© 2026 IX TEAM

---

📌 함께 보면 좋은 글

• Claude Code 토큰 65% 절감 케이브맨 스킬, 진짜 쓸 만한 건 따로 있다
• Claude Code 토큰 65% 줄여주는 "케이브맨(Caveman)" 스킬 - AI한테 원시인처럼 말하라고 시켰더니
• ClaudeClAW v3 멀티에이전트 OS 분석