Post

첫 번째 Crew 만들기

복잡한 문제를 함께 해결할 수 있는 협업형 AI 팀을 만드는 단계별 튜토리얼.

Posted Updated
By mminzy22
views 17 min read
첫 번째 Crew 만들기

협업형 AI의 잠재력 열기

CrewAI는 단일 AI로는 어려운 작업을 여러 AI가 협력하여 수행할 수 있도록 해주는 프레임워크입니다.

이 가이드에서는 하나의 주제를 조사하고 분석하여 종합 보고서를 작성하는 “리서치 크루”를 만드는 과정을 따라갑니다.

이 가이드를 마치면 다음을 얻게 됩니다

  1. 명확한 역할과 책임을 가진 AI 리서치 팀 구성
  2. 다중 에이전트 간 협업 오케스트레이션 수행
  3. 정보 수집, 분석, 보고서 작성이 자동화된 복잡한 워크플로우 구현
  4. 앞으로 더 복잡한 프로젝트에 활용할 수 있는 기본 역량 습득

이번 튜토리얼에서는 단순한 리서치 크루를 만들지만, 이와 동일한 패턴은 다음과 같은 고급 시나리오에도 활용할 수 있습니다:

  • 작가, 편집자, 팩트체커가 포함된 다단계 콘텐츠 제작 팀
  • 단계별 지원 담당자가 포함된 고객 서비스 시스템
  • 데이터 수집, 시각화, 인사이트 도출을 자동화하는 비즈니스 분석 팀
  • 아이디어 발굴부터 설계 및 구현 계획까지 수행하는 제품 개발 팀

사전 준비 사항

시작 전에 다음을 확인하세요:

  1. 설치 가이드를 따라 CrewAI를 설치했는지
  2. OpenAI API 키를 환경 변수로 설정했는지
  3. Python에 대한 기초적인 이해가 있는지

1단계: 새 CrewAI 프로젝트 생성하기

CLI를 이용해 새로운 CrewAI 프로젝트를 만듭니다. 이 명령어는 필요한 모든 파일이 포함된 프로젝트 구조를 자동으로 생성해줍니다.

1
2

crewai create crew research_crew
cd research_crew

위 명령을 실행하면 다음이 자동으로 생성됩니다:

  • 프로젝트 디렉터리 및 필수 파일
  • 에이전트와 태스크 구성용 설정 파일
  • 기본 Crew 구현 파일
  • 크루 실행을 위한 main 스크립트
CrewAI Framework Overview

2단계: 프로젝트 구조 살펴보기

CLI가 만들어준 프로젝트 구조:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

research_crew/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
└── src/
    └── research_crew/
        ├── __init__.py
        ├── main.py
        ├── crew.py
        ├── tools/
        │   ├── custom_tool.py
        │   └── __init__.py
        └── config/
            ├── agents.yaml
            └── tasks.yaml

이 구조는 Python 프로젝트의 베스트 프랙티스를 따르며, 확장성과 유지보수가 쉬운 구조입니다. 특히 설정 파일은 YAML, 실행 로직은 Python 코드로 분리되어 있어, 로직을 수정하지 않고도 크루의 행동을 손쉽게 변경할 수 있습니다.

3단계: 에이전트 정의하기

CrewAI에서 에이전트는 특정 역할, 목표, 배경을 가진 전문화된 존재입니다. 이들은 마치 각본 속 인물처럼 고유의 성격과 목적을 가지고 행동합니다.

리서치 크루에는 두 명의 에이전트를 만듭니다다:

  1. 정보를 잘 찾고 구조화하는 리서처
  2. 수집된 정보를 분석하고 보고서를 작성하는 애널리스트

agents.yaml 파일을 아래와 같이 수정하세요:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# src/research_crew/config/agents.yaml
researcher:
  role: >
    {topic} 분야의 시니어 리서치 스페셜리스트
  goal: >
    {topic}에 대한 포괄적이고 정확한 정보를 수집하되,
    최근 동향과 핵심 인사이트에 집중하세요
  backstory: >
    다양한 출처에서 관련 정보를 빠르게 찾아내는 데 뛰어난 능력을 가진 리서치 전문가입니다.
    정보를 구조화하고 복잡한 주제를 이해하기 쉽게 정리하는 데 탁월합니다.
  llm: openai/gpt-4o-mini

analyst:
  role: >
    {topic}에 대한 데이터 분석 및 보고서 작성자
  goal: >
    리서치 결과를 분석하여, 명확하고 통찰력 있는 종합 보고서를 작성하세요
  backstory: >
    데이터 해석과 기술 글쓰기 배경을 가진 분석가입니다.
    패턴을 식별하고 의미 있는 인사이트를 도출한 후, 이를 구조화된 보고서로 잘 전달하는 데 능합니다.
  llm: openai/gpt-4o-mini

각 에이전트는 고유한 역할(role), 목표(goal), 배경(backstory)을 가지며, 이는 단순한 설명이 아니라 에이전트의 작업 방식에 직접적인 영향을 줍니다. 이들을 세심하게 설계하면 서로를 보완하는 유능한 팀을 만들 수 있습니다.

4단계: 태스크 정의하기

에이전트를 정의했으니 이제 실제로 수행할 작업(Task)을 설정해야 합니다. CrewAI에서 태스크는 에이전트가 수행할 구체적인 작업 지시와 예상 출력 결과를 의미합니다.

이번 리서치 크루에는 다음 두 가지 주요 태스크를 정의합니다:

  1. 리서치 태스크 – 포괄적인 정보 수집
  2. 분석 태스크 – 인사이트가 담긴 종합 보고서 작성

tasks.yaml 파일을 다음과 같이 수정하세요:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# src/research_crew/config/tasks.yaml
research_task:
  description: >
    {topic}에 대한 철저한 리서치를 수행하세요. 다음 항목을 포함해야 합니다:
    1. 주요 개념과 정의
    2. 역사적 배경과 최근 동향
    3. 주요 도전 과제와 기회 요인
    4. 대표적인 활용 사례 또는 사례 연구
    5. 향후 전망과 잠재적 발전 방향

    정보를 명확한 섹션으로 구조화하여 정리하세요.
  expected_output: >
    {topic}에 대한 모든 항목을 포함한 구조화된 리서치 문서. 필요 시 구체적인 수치, 예시 포함.
  agent: researcher

analysis_task:
  description: >
    리서치 결과를 바탕으로 {topic}에 대한 종합 보고서를 작성하세요. 다음 사항을 포함해야 합니다:
    1. 간결한 요약 (executive summary)
    2. 핵심 정보 포함
    3. 트렌드 및 패턴에 대한 분석
    4. 향후 고려사항 및 추천사항
    5. 명확한 제목 구조와 전문가 스타일의 포맷
  expected_output: >
    {topic}에 대한 종합 분석 보고서. 명확한 섹션 구성을 갖추고, 요약-본문-결론 형식으로 구성.
  agent: analyst
  context:
    - research_task
  output_file: output/report.md

context 항목에 주목합니다. 이는 분석 태스크가 리서치 태스크의 출력물을 참조할 수 있도록 해주는 매우 중요한 기능입니다. 마치 실제 팀에서 정보가 흐르듯, 에이전트 간 자연스러운 협업 흐름을 만듭니다.

5단계: 크루 구성하기

이제 모든 요소를 조합하여 하나의 크루로 구성합니다. 크루는 에이전트들이 함께 협력하여 태스크를 수행하도록 오케스트레이션하는 컨테이너 역할을 합니다.

crew.py 파일을 아래와 같이 구성하세요:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

# src/research_crew/crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List

@CrewBase
class ResearchCrew():
    """연구 주제에 대한 종합 분석 및 보고서를 위한 리서치 크루 정의"""

    agents: List[BaseAgent]
    tasks: List[Task]

    @agent
    def researcher(self) -> Agent:
        return Agent(
            config=self.agents_config['researcher'],
            verbose=True,
            tools=[SerperDevTool()]  # 웹 검색 도구 사용
        )

    @agent
    def analyst(self) -> Agent:
        return Agent(
            config=self.agents_config['analyst'],
            verbose=True
        )

    @task
    def research_task(self) -> Task:
        return Task(
            config=self.tasks_config['research_task']
        )

    @task
    def analysis_task(self) -> Task:
        return Task(
            config=self.tasks_config['analysis_task'],
            output_file='output/report.md'
        )

    @crew
    def crew(self) -> Crew:
        """리서치 크루 실행 흐름 구성"""
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,
            verbose=True,
        )

이 코드에서 다음을 설정했습니다:

  1. SerperDevTool을 활용해 웹 검색이 가능한 리서처 에이전트 생성
  2. 분석 태스크 수행을 위한 애널리스트 에이전트 생성
  3. 리서치 및 분석 태스크 정의
  4. 크루의 실행 순서 설정 (리서치 → 분석 순차 실행)

이처럼 간결한 코드만으로도, 복잡한 협업형 AI 시스템을 정의할 수 있습니다. CrewAI가 내부에서 복잡한 협업 처리 로직을 대신 처리해주기 때문입니다.

6단계: 메인 스크립트 작성하기

이제 크루를 실행할 메인 스크립트를 만듭니다. 여기서 리서치할 주제를 지정할 수 있습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

#!/usr/bin/env python
# src/research_crew/main.py
import os
from research_crew.crew import ResearchCrew

# 출력 디렉토리가 없으면 생성
os.makedirs('output', exist_ok=True)

def run():
    """
    리서치 크루 실행
    """
    inputs = {
        'topic': '인공지능 기반 헬스케어 기술'
    }

    # 크루 생성 및 실행
    result = ResearchCrew().crew().kickoff(inputs=inputs)

    # 결과 출력
    print("\n\n=== 최종 보고서 ===\n\n")
    print(result.raw)

    print("\n\n보고서는 output/report.md 에 저장되었습니다")

if __name__ == "__main__":
    run()

이 스크립트는:

  1. 출력 폴더 생성
  2. 리서치 주제 설정
  3. 크루 실행 및 결과 출력

CrewAI의 장점은 바로 이 간단한 코드로 여러 AI 에이전트를 협업 구조로 실행할 수 있다는 점입니다.

7단계: 환경 변수 설정하기

API 키를 .env 파일에 저장하세요:

1
2

OPENAI_API_KEY=your_openai_api_key
SERPER_API_KEY=your_serper_api_key

Serper API 키는 Serper.dev에서 무료로 발급받을 수 있습니다.

8단계: 의존성 설치하기

CrewAI CLI를 이용해 필요한 패키지를 설치하세요:

1

crewai install

이 명령어는:

  1. pyproject.toml에서 의존성 읽기
  2. 가상환경 생성 (필요 시)
  3. 모든 패키지 설치

9단계: 크루 실행하기

AI 크루를 실행

1

crewai run

에이전트들이 다음 순서로 작업을 수행합니다:

  1. 리서처가 정보 수집
  2. 애널리스트가 리서치 기반 보고서 생성

이 과정에서 에이전트의 사고 흐름, 행동, 출력 결과를 실시간으로 확인할 수 있습니다.

10단계: 결과물 확인하기

작업이 끝나면 output/report.md 파일에 최종 보고서가 생성됩니다. 보고서에는 다음 내용이 포함됩니다:

  1. Executive Summary (요약)
  2. 주제에 대한 상세 정보
  3. 분석과 인사이트
  4. 향후 고려사항 및 제안

추가 CLI 명령어 알아보기

CrewAI는 다양한 CLI 명령어를 제공합니다:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 사용 가능한 모든 명령어 보기
crewai --help

# 크루 실행
crewai run

# 테스트 실행
crewai test

# 크루 메모리 초기화
crewai reset-memories

# 특정 태스크부터 다시 실행
crewai replay -t <task_id>

첫 번째 크루, 그 이후에는?

다음과 같은 확장이 가능합니다:

크루 확장하기

  • 팩트체커: 리서치 검증
  • 데이터 시각화 전문가: 차트/그래프 생성
  • 도메인 전문가: 특정 분야의 깊이 있는 지식 제공
  • 비평가: 분석 내용에 대한 피드백 제공

도구 확장하기

  • 웹 브라우징 툴
  • CSV/DB 분석 툴
  • 코드 실행 도구
  • 외부 API 연동

복잡한 흐름 설계

  • 매니저 → 워커 구조의 계층적 흐름
  • 피드백을 활용한 반복형 흐름
  • 에이전트 병렬 실행
  • 결과 기반으로 흐름을 조정하는 동적 프로세스

다양한 분야에 적용하기

  • 콘텐츠 제작: 작가, 편집자, 검증자 협업
  • 고객 서비스: 티어 기반 상담 시스템
  • 제품 개발: 리서처-디자이너-기획자 협업
  • 데이터 분석: 수집-분석-시각화 흐름
CrewAI
TIL CrewAI Crew Flow
This post is licensed under CC BY 4.0 by the author.