Building Multi-Agent Systems With CrewAI - A Comprehensive Tutorial

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

CrewAI의 역할 기반 에이전트와 Firecrawl 웹 검색을 결합해 다중 에이전트 시스템을 구성하는 튜토리얼로, 제공된 본문은 항공편 검색·추천 예제를 구현하며 ChatGPT 복제와 Streamlit UI는 학습 목표로 제시한다.

📌 핵심 요약

• 원문은 2026년 에이전트 개발에서 운영 신뢰성, 평가, 도구 거버넌스가 중요해졌다고 설명하며, CrewAI의 역할·목표·배경 설정과 YAML 기반 구성 분리, Streamlit 채팅 UI를 주요 개발 방향으로 제시한다.
• CrewAI에는 FirecrawlSearchTool, FirecrawlScrapeWebsiteTool, FirecrawlCrawlWebsiteTool이 제공된다. 웹 검색은 에이전트가 직접 질의를 작성하며, 별도의 llm 설정이 없으면 OpenAI 모델을 사용하므로 예제에는 FIRECRAWL_API_KEY와 OPENAI_API_KEY가 필요하다.
• FirecrawlSearchTool에 config를 전달하면 기본값을 대체한다. limit=5와 tbs="qdr:w"만 지정한 예제는 최근 일주일의 제목·URL·설명을 반환하며, 페이지 본문이 필요하면 scrape_options에 Markdown 형식을 추가해야 한다. 원문이 제시한 2026년 10월 기준 검색 비용은 결과 10개당 2크레딧을 올림 적용하고, 기본 Markdown 스크래핑은 페이지당 1크레딧을 추가한다.
• CrewAI는 적응적 문제 해결을 위한 자율 협업 방식인 Crews와, 상태를 세밀하게 관리하는 결정적·이벤트 기반 방식인 Flows를 구분한다. 원문은 역할 분담과 도구 통합이 디버깅·유지보수·신뢰성에 도움이 된다고 주장한다.
• 항공편 예제는 Travel Search Specialist와 Travel Consultant에 검색과 추천을 나누고 allow_delegation=False로 위임을 막는다. Task의 expected_output은 응답 형식 예시이며, Crew.kickoff()에 New York→London, June 15th, 2026 등의 입력을 전달해 순차 실행한다. 제공된 본문은 고급 기능 소개 도중 끝나며 ChatGPT 복제, 테스트, Streamlit UI의 실제 구현은 포함하지 않는다.

🧩 주요 포인트

1. 역할·목표·배경과 Task별 책임을 명시하면 검색과 해석의 경계가 드러난다 → 항공편 예제는 역할 분리가 실행 흐름과 디버깅을 이해하는 데 어떻게 쓰이는지 보여준다.
2. Firecrawl의 config 대체 규칙과 scrape_options 유무가 반환 정보와 크레딧 사용량을 바꾼다 → 검색 결과의 메타데이터만 필요한지, 페이지 본문까지 필요한지에 따라 구성을 구분해야 한다.
3. Crews와 Flows는 자율성과 실행 통제라는 서로 다른 요구를 지원한다 → 제공된 순차 실행 예제와, 아직 구현이 제시되지 않은 ChatGPT 복제·Streamlit UI 목표를 구분해 튜토리얼의 범위를 판단할 필요가 있다.

🧠 상세 정리

1. 2026년 에이전트 생태계와 튜토리얼의 목표

원문은 2026년 AI 에이전트 시장이 계속 확대되고 있으며, 남은 2020년대에도 강한 성장이 예상된다는 배경에서 출발한다. 개발팀의 관심도 단순한 기능 확장을 넘어 운영 신뢰성, 평가, 도구 거버넌스로 넓어졌으며, 다중 에이전트 시스템은 연구용 시연에서 실제 운영으로 이동했다고 설명한다. 프레임워크 비교에서는 LangGraph의 상태 기반 오케스트레이션, Dify의 로코드 접근, CrewAI의 역할 기반 구조를 소개하고, TypeScript 진영의 Flue와 Eve는 엣지 런타임과 서버리스 배포를 겨냥한다고 덧붙인다. 튜토리얼의 목표는 프로젝트 초기화부터 에이전트·작업 정의, 실행 조율, 테스트, Streamlit UI까지 거쳐 다중 에이전트 ChatGPT 복제를 만드는 것이다. 다만 이 목표 전체가 제공된 본문에서 구현되지는 않으므로, 학습 계획과 실제로 제시된 항공편 예제를 구분해 읽어야 한다.

2. Firecrawl을 연결해 에이전트에 웹 검색 제공

웹 검색 연결은 Firecrawl Python SDK와 CrewAI 도구 패키지를 설치하고, FirecrawlSearchTool 인스턴스를 에이전트의 tools 목록에 넣는 방식으로 설명된다. CrewAI에는 검색용 FirecrawlSearchTool 외에도 개별 웹사이트 스크래핑용 FirecrawlScrapeWebsiteTool과 웹사이트 크롤링용 FirecrawlCrawlWebsiteTool이 제공된다. 검색 에이전트는 작업에 맞는 질의를 직접 작성하며, Firecrawl 검색 API는 결과의 제목·URL·설명을 반환하고 스크래핑을 요청하면 해당 페이지 내용도 함께 제공한다. 첫 예제의 Web researcher는 최신 웹 자료로 답하고 사용한 URL을 인용하도록 설정되며, 이번 주 주요 AI 에이전트 프레임워크 발표를 출처 URL이 붙은 다섯 개 항목으로 정리하는 작업을 맡는다. 또한 에이전트에 llm을 별도로 지정하지 않으면 OpenAI 모델을 사용하므로, 예제는 FIRECRAWL_API_KEY와 OPENAI_API_KEY를 모두 설정한다.

3. 검색 설정의 대체 규칙과 크레딧 비용

FirecrawlSearchTool의 config는 생성 시 검색 옵션을 지정하는 사전이며, 원문은 이를 전달하면 기본 설정을 대체한다는 점을 강조한다. 따라서 limit=5와 tbs="qdr:w"를 지정한 예제는 최근 일주일의 검색 결과 다섯 개에 대한 제목·URL·설명을 받지만 페이지 본문은 받지 않는다. 본문까지 읽게 하려면 scrape_options에 formats를 ["markdown"]으로 지정해야 하며, 옵션 표에는 결과 수, 시간 필터, 지역, 밀리초 단위 요청 제한 시간과 스크래핑 설정이 소개된다. 원문이 인용한 기본값은 2026년 10월 Firecrawl CrewAI 문서 기준으로, 결과 수는 5개이고 기본 스크래핑은 주요 콘텐츠의 Markdown을 반환한다. 비용은 검색 결과 10개당 2크레딧을 올림 적용하고 기본 Markdown 스크래핑은 페이지당 1크레딧을 추가하므로, 스크래핑을 제외하면 Free 요금제의 월 1,000크레딧으로 최대 10개 결과를 받는 검색 500회를 수행할 수 있다고 설명한다.

4. 역할 기반 구조와 Crews·Flows의 차이

CrewAI는 다른 에이전트 시스템과 독립적으로 구축된 프레임워크로 소개되며, 전문성과 책임이 분명한 역할 기반 에이전트를 통해 복잡한 작업을 나누는 데 초점을 둔다. 원문은 이러한 분리가 반복 실행에서 행동의 일관성을 높이고, 유지보수 부담과 운영 환경의 디버깅 난도를 낮춘다고 주장한다. 주요 기능으로는 역할 기반 에이전트, 외부 서비스와의 유연한 도구 통합, 협업을 통한 작업 조율, 두 가지 워크플로 관리 방식, 보안과 토큰 비용 효율을 고려한 설계를 제시한다. 이 가운데 Crews는 적응적 문제 해결이 필요한 상황에서 에이전트의 자율 협업을 제공하고, Flows는 결정적·이벤트 기반 오케스트레이션과 세밀한 상태 관리를 제공한다. 원문은 두 방식을 함께 활용하면 구조화된 절차와 지능적 의사결정을 결합할 수 있다고 설명하지만, 신뢰성이나 비용 개선을 입증하는 정량적 비교 결과는 제시하지 않는다.

5. 항공편 예제의 준비와 두 에이전트의 책임

실습은 항공편을 검색하고 결과를 추천으로 정리하는 작은 시스템으로 시작하며, CrewAI의 핵심 구성요소인 Agent, Task, Crew를 소개한다. 준비 단계에서는 CrewAI와 도구 패키지, Firecrawl Python 패키지, python-dotenv를 설치하고, 코드에서 필요한 클래스를 가져온 뒤 load_dotenv()로 환경변수를 불러온다. 원문은 FirecrawlSearchTool에 고정 질의를 지정하지 않아 에이전트가 작업 요구에 맞춰 검색어를 구성하도록 한다고 설명한다. Travel Search Specialist는 가격과 편의성을 고려한 항공편 탐색을 맡고 Firecrawl 검색 도구를 사용하며, Travel Consultant는 복잡한 여행 정보를 명확하고 실행 가능한 추천으로 바꾸는 역할을 맡는다. 각 에이전트의 role, goal, backstory가 행동과 응답의 방향을 정하고, 두 에이전트 모두 allow_delegation=False로 설정되어 다른 에이전트에게 작업을 위임하지 않는다.

6. Task 정의와 expected_output의 역할

검색 작업의 description에는 {trip_type}, {origin}, {destination}, {travel_date} 같은 변수가 들어가며, 실제 실행 시 전달한 입력으로 채워진다. 첫 번째 Task는 항공편 탐색을 담당하고, 두 번째 Task는 검색된 항공편의 예약 선택지를 분석해 전반적인 가치가 가장 좋은 방안을 추천하도록 정의된다. expected_output에는 Chicago에서 Miami로 가는 1월 15일 항공편 세 개와 예약 추천 형식이 예시로 들어가며, United Airlines 178달러, American Airlines 195달러, Southwest 210달러 등의 값이 포함된다. 이 내용은 에이전트가 따라야 할 응답 형태를 보여주는 템플릿이므로, 실제 검색으로 확인된 항공편 가격이나 현재 예약 조건으로 받아들여서는 안 된다. 작업 정의는 탐색과 해석의 책임을 나누면서 출발·도착 시각, 가격, 예약 경로, 부가 조건처럼 최종 추천에 담길 정보의 형태를 구체적으로 보여준다.

7. Crew 구성과 입력에 따른 순차 실행

Crew는 flights_agent와 summarize_agent를 agents 목록에, 검색 작업과 예약 추천 작업을 tasks 목록에 넣어 구성하며, 작업 실행과 에이전트 간 흐름을 조율한다. 예제는 verbose=True로 상세 실행 로그를 표시해 실행 과정을 관찰하고 디버깅할 수 있도록 설정한다. 실제 실행에서는 Crew.kickoff()의 inputs에 one-way, New York, London, June 15th, 2026을 전달하며, 앞서 Task 설명에 둔 변수들이 이 값으로 채워진다. 원문은 검색 에이전트가 먼저 선택지를 찾고 추천 에이전트가 그 결과를 정리하는 순차 흐름으로 설명하며, 제시된 출력 예시는 American Airlines의 285달러 항공편을 가격과 일정의 균형이 좋은 선택으로 소개한다. 이 출력에는 JFK 19시 출발, 다음 날 LHR 7시 30분 도착, 비행시간 7시간 30분 등의 세부 정보가 나오지만, 본문에 실린 실행 결과 예시라는 맥락을 유지해야 한다.

8. 확장 방향과 제공된 본문의 범위

도입부의 핵심 제안은 역할·목표·배경을 명시해 행동을 이해하기 쉽게 만들고, 에이전트와 작업 설정을 YAML로 분리하며, 도구와 실행 조율을 결합해 시스템을 확장하는 것이다. Firecrawl은 검색뿐 아니라 심층 조사와 추출 기능을 제공해 스크래핑 인프라를 직접 관리하는 부담을 줄이는 도구로 소개되고, Streamlit은 간단한 채팅 인터페이스를 빠르게 붙이는 수단으로 제안된다. 항공편 예제 뒤에서는 복잡한 워크플로 관리, 계층형 에이전트 구조, 문맥 유지를 위한 메모리 시스템 같은 고급 기능을 지원한다고 설명한다. 그러나 제공된 본문은 추가 통합 기능을 언급하는 문장 중간에서 끝나므로, 이후 기능이나 구현 내용을 확인할 수 없다. 따라서 이 자료에서 구체적으로 확인되는 구현은 Firecrawl 검색을 사용하는 역할 분담과 Task·Crew 실행이며, YAML 프로젝트 구성, ChatGPT 복제, 테스트 절차, Streamlit UI는 실제 코드가 제시된 내용과 구분된다.

🧾 핵심 주장 / 시사점

• 역할 분리는 검색과 추천의 책임을 드러내지만, expected_output에 들어간 구체적인 가격과 예약 조건은 형식 예시다. 응답 형식을 안내하는 정보와 실제 검색 결과를 구분하는 것이 예제를 해석하는 핵심이다.
• Firecrawl의 검색 결과 메타데이터와 페이지 본문은 정보의 깊이와 비용이 다르다. 특히 config가 기본값을 대체하므로, 검색 옵션을 일부 지정하는 것만으로도 반환 콘텐츠의 범위가 달라질 수 있다.
• 원문은 운영 수준의 신뢰성과 통제 가능성을 강조하지만, 제공된 구현은 두 에이전트의 순차 작업에 집중한다. 이 예제만으로 Crews·Flows의 전체 기능이나 완성된 ChatGPT 복제의 동작을 검증했다고 보기는 어렵다.

✅ 액션 아이템

• FirecrawlSearchTool의 config와 scrape_options를 검토해 제목·URL·설명만 받을지 페이지 본문까지 받을지 정하고, 검색 10개당 2크레딧과 페이지당 추가 1크레딧을 반영한다.
• Travel Search Specialist와 Travel Consultant의 검색·추천 책임 및 allow_delegation=False 설정을 확인하고, expected_output을 실제 항공편 정보와 구분해 해석한다.
• ChatGPT 복제와 Streamlit UI의 구현 범위를 판단할 때, 제공된 본문의 Crew.kickoff() 순차 실행 예제와 실제 구현이 포함되지 않은 목표를 구분한다.

❓ 열린 질문

• FirecrawlSearchTool을 사용할 작업에는 제목·URL·설명만으로 충분한가, 아니면 scrape_options를 통해 페이지 본문까지 받아야 하는가?
• 구현하려는 작업 흐름에는 Crews의 자율 협업과 Flows의 결정적·이벤트 기반 제어 중 어떤 방식이 더 적합한가?
• 제공된 본문에 실제 구현이 포함되지 않은 ChatGPT 복제, 테스트, Streamlit UI는 어떤 내용으로 이어지는가?