첫 크루 만들기 (First Crew)

이번에는 CrewAI로 첫 크루를 만들어 볼게요. 주제 하나를 정하면, 두 명의 에이전트가 각자 역할을 맡아 조사하고 그 결과를 마크다운 보고서로 정리해 주는 리서치 크루예요. 개념을 하나씩 짚어가며 직접 돌려볼 수 있게 구성했어요.

개념 (Concept)

CrewAI의 크루 프로젝트는 이제 JSON-first로 만들어져요. 파이썬 코드로 에이전트를 정의하던 예전 방식 대신, JSON 계열 파일에 정의를 담고 CLI가 그대로 읽어 실행하는 구조예요.

agents/*.jsonc — 에이전트 정의. researcher, analyst처럼 파일 이름이 곧 crew.jsonc에서 참조하는 이름이 돼요.
crew.jsonc — 크루 설정, 태스크 순서, 프로세스, 메모리, 런타임 입력값.
crewai run — 이 JSON 정의를 직접 로드해서 크루를 실행해요.

에이전트가 각각 뭘 하는지 먼저 볼게요. researcher는 주제를 조사하는 역할이고, analyst는 조사 결과를 받아서 보고서로 다듬는 역할이에요. 두 번째 태스크가 context로 첫 태스크의 결과를 넘겨받는 구조죠.

코드 스니펫 (Code)

1. 새 크루 만들기

CLI가 JSON-first 프로젝트를 생성해 줘요.

crewai create crew research_crew
cd research_crew

생성하면 이런 구조가 나와요.

research_crew/
├── .gitignore
├── .env
├── agents/
│   └── researcher.jsonc
├── crew.jsonc
├── knowledge/
├── pyproject.toml
├── README.md
├── skills/
└── tools/

2. 에이전트 정의하기

생성된 agents/researcher.jsonc를 교체하고 agents/analyst.jsonc를 추가해요.

agents/researcher.jsonc:

{
  "role": "Senior Research Specialist for {topic}",
  "goal": "Find comprehensive and accurate information about {topic}, with a focus on recent developments and key insights.",
  "backstory": "You are an experienced research specialist who organizes complex information into clear, useful notes.",
  // Replace with your model, for example "openai/gpt-4o".
  "llm": "provider/model-id",
  "tools": ["SerperDevTool"],
  "settings": {
    "verbose": true,
    "allow_delegation": false
  }
}

agents/analyst.jsonc:

{
  "role": "Report Analyst for {topic}",
  "goal": "Turn research findings into a clear, well-structured report.",
  "backstory": "You are a careful analyst with strong technical writing skills and a talent for extracting useful insights.",
  // Replace with your model, for example "openai/gpt-4o".
  "llm": "provider/model-id",
  "settings": {
    "verbose": true,
    "allow_delegation": false
  }
}

llm의 provider/model-id는 자신이 쓰는 모델로 바꿔줘야 해요. 예를 들어 openai/gpt-4o, anthropic/claude-sonnet-4-6, gemini/gemini-2.0-flash-001처럼요.

3. 태스크와 크루 설정

crew.jsonc를 이렇게 교체해요.

{
  "name": "Research Crew",
  "agents": ["researcher", "analyst"],
  "tasks": [
    {
      "name": "research_task",
      "description": "Conduct thorough research on {topic}. Focus on key concepts, recent developments, major challenges, notable applications, and future outlook.",
      "expected_output": "A comprehensive research document with organized sections, specific facts, and useful examples about {topic}.",
      "agent": "researcher"
    },
    {
      "name": "analysis_task",
      "description": "Analyze the research findings and create a polished report on {topic}. Include an executive summary, key insights, trend analysis, and recommendations.",
      "expected_output": "A professional markdown report with clear headings, a concise summary, main findings, and recommendations.",
      "agent": "analyst",
      "context": ["research_task"],
      "output_file": "output/report.md",
      "markdown": true
    }
  ],
  "process": "sequential",
  "verbose": true,
  "memory": true,
  "inputs": {
    "topic": "Artificial Intelligence in Healthcare"
  }
}

눈여겨볼 점이 두 가지예요. context는 앞서 실행된 태스크의 이름을 가리키는데, 덕분에 analyst가 researcher의 조사 결과를 받아서 써요. 그리고 inputs 객체는 {topic}의 기본값을 제공하는데, 이 기본값을 지우면 crewai run이 실행 시점에 프롬프트로 물어봐요.

4. 환경 변수 설정

.env를 열어서 모델과 도구에 필요한 키를 추가해요.

SERPER_API_KEY=your_serper_api_key
# Add your model provider API key here too.

프로바이더별 키는 LLM 설정 가이드를 참고하면 돼요.

5. 설치하고 실행하기

crewai install
crewai run

crewai run은 crew.jsonc를 감지하고 agents/에서 에이전트를 로드해서, 비어 있는 플레이스홀더를 물어본 뒤 크루를 실행해요. 실행이 끝나면 output/report.md를 열면 돼요.

실무 관점 (Practice)

JSON-first가 바꾸는 것: 에이전트·태스크 정의가 코드와 분리되면서, 크루 구조만 바꿔 재실행하기 쉬워져요. 팀끼리 설정 파일을 공유하기에도 유리해요.
결과가 파일로 나온다: 마지막 태스크가 output_file로 output/report.md를 작성해요. 결과물이 콘솔에만 남는 게 아니라 재사용·배포 대상이 되죠.
context로 이어붙이기: 순차 크루에서 앞 태스크의 출력을 뒤 태스크가 쓸 때는 반드시 context: ["앞태스크이름"]을 지정해야 해요. 빼먹으면 analyst가 아무 맥락 없이 보고서를 쓰려고 하게 돼요.
모델·도구 키는 별도 관리: .env에 키를 두므로, 정의 파일 자체는 키 없이 버전 관리할 수 있어요. provider/model-id가 항상 실제 모델로 치환되어 있는지 확인하세요.
verbose와 memory: 디버그할 때는 verbose가 실행 로그를 보여주고, memory는 크루가 이전 실행 맥락을 기억하게 해요.

더 알아보기 (Learn More)

에이전트를 늘리려면 agents/<name>.jsonc 파일을 새로 만들고 crew.jsonc의 agents 배열에 나열해요.
태스크를 늘리려면 tasks 배열에 객체를 추가해요.
내장 도구를 쓰려면 "FileReadTool", "SerperDevTool" 같은 클래스 이름을 추가해요.
커스텀 도구는 "custom:<name>"으로 지정하며, tools/<name>.py를 로드해요.
계층적 실행은 "process": "hierarchical"로 바꾸고 manager_llm이나 manager_agent를 지정하면 돼요.

원문: Build Your First Crew