CrewAI 디버깅과 자주 나는 오류: 초보가 가장 자주 터뜨리는 8가지

현실적으로 Agent 개발에서 가장 오래 걸리는 건 구현이 아니라 디버깅입니다.
이 글은 돌아가는 길을 줄여주는 지뢰 지도입니다.

가장 흔한 8가지 문제

현상	흔한 원인	빠른 해결
출력 형식이 매번 다름	expected_output이 모호함	형식 제약 추가, 필요 시 output_pydantic 사용
후속 Task가 데이터를 못 받음	context 누락	tasks.yaml에서 연결을 명시
Tool이 전혀 호출되지 않음	Task에 Tool 사용 조건 없음	Task 지시에 "먼저 Tool 사용" 강제
비용 급증	Task가 길고 반복 호출 많음	Task 분할, 프롬프트 축소, 캐시 추가
환각 심함	출처 제약 없음	source URL과 인용 형식 요구
흐름 멈춤	분기 조건 불완전	router 반환값과 listener 매핑 확인
시작하자마자 에러	환경 변수 미설정	.env와 API Key 점검
성능 편차 큼	테스트 입력이 고정되지 않음	고정 입력/검수 규칙 수립

권장 디버깅 순서

1. 설정 확인: agents.yaml, tasks.yaml
2. 입력 확인: inputs 안정성
3. Tool 확인: 파라미터와 반환 형식
4. 마지막으로 모델 확인: 온도, 컨텍스트 길이, 비용

순서를 바꾸지 마세요. 모델 문제처럼 보이지만 YAML 한 줄 누락인 경우가 많습니다.

유용한 작은 팁

각 Task에 "출력 요약"과 "핵심 필드 체크"를 넣어두세요:

• 결론이 있는가?
• 출처가 있는가?
• markdown 구조를 지켰는가?

워크플로 내부의 작은 단위 테스트처럼 동작합니다.

다음 단계

마지막 글에서 지금까지 내용을 운영 기준으로 묶어 정리합니다.
👉 프로덕션 베스트 프랙티스