퀵스타트

퀵스타트 (Quickstart)

몇 분 안에 첫 CrewAI Flow를 만들어봐요 — 오케스트레이션, 상태(state), 그리고 실제 리포트를 만들어내는 에이전트 크루까지 한 번에 구성할 수 있어요.

출처: 문서

본문

코딩 에이전트 스킬로 CrewAI 에이전트 & Flow 만들기 (Watch)

CrewAI로 코딩 에이전트를 빠르게 시작할 수 있도록 코딩 에이전트 스킬(Claude Code, Codex 등)을 설치할 수 있어요. npx skills add crewaiinc/skills 명령어로 설치하면 됩니다.

이 가이드에서는 Flow를 만들어서, 연구 주제를 설정하고, 한 명의 에이전트가 포함된 크루(웹 검색을 사용하는 연구자)를 실행하며, 마지막에 마크다운 리포트를 디스크에 저장합니다. Flow는 프로덕션 앱을 구조화할 때 권장되는 방식이에요. Flow가 **상태(state)**와 실행 순서를 담당하고, 에이전트는 크루 단계 안에서 실제 작업을 수행합니다.

아직 CrewAI를 설치하지 않았다면, 먼저 설치 가이드를 따라주세요.

준비 사항 (Prerequisites)

• Python 환경과 CrewAI CLI (참고: 설치)
• 올바른 API 키로 설정된 LLM (참고: LLM)
• 이 튜토리얼의 웹 검색에 필요한 Serper.dev API 키 (SERPER_API_KEY)

첫 Flow 만들기 (Build your first Flow)

1. Flow 프로젝트 만들기

터미널에서 Flow 프로젝트를 스캐폴딩합니다 (폴더 이름은 밑줄을 사용해요, 예: latest_ai_flow):

crewai create flow latest-ai-flow
cd latest_ai_flow

이렇게 하면 src/latest_ai_flow/ 아래에 Flow 앱이 생성되고, crews/content_crew/ 안에 스타터 크루가 포함됩니다. 다음 단계에서 이 크루를 최소한의 단일 에이전트 연구 크루로 교체할 거예요.

2. JSONC 파일에서 에이전트 하나를 설정하기

src/latest_ai_flow/crews/content_crew/agents/researcher.jsonc 파일을 만듭니다 (필요하면 agents/ 디렉터리를 먼저 생성하세요). {topic} 같은 변수는 crew.kickoff(inputs=...)에서 채워집니다.

{
  "role": "{topic} Senior Data Researcher",
  "goal": "Uncover cutting-edge developments in {topic}",
  "backstory": "You're a seasoned researcher who finds relevant information and presents it clearly.",
  "tools": ["SerperDevTool"],
  "settings": {
    "verbose": true
  }
}

3. crew.jsonc에서 크루 설정하기

src/latest_ai_flow/crews/content_crew/crew.jsonc 파일을 만듭니다:

{
  "name": "Research Crew",
  "agents": ["researcher"],
  "tasks": [
    {
      "name": "research_task",
      "description": "Conduct thorough research about {topic}. Use web search to find recent, credible information.",
      "expected_output": "A markdown report with clear sections: key trends, notable tools or companies, and implications. Aim for 800-1200 words. No fenced code blocks around the whole document.",
      "agent": "researcher",
      "output_file": "output/report.md",
      "markdown": true
    }
  ],
  "process": "sequential",
  "verbose": true
}

4. JSON 크루 불러오기 (content_crew.py)

생성된 content_crew.py를 crew.jsonc를 Crew로 바꿔주는 작은 로더로 교체합니다.

# src/latest_ai_flow/crews/content_crew/content_crew.py
from pathlib import Path

from crewai.project import load_crew

def kickoff_content_crew(inputs: dict):
  crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
  return crew.kickoff(inputs={**default_inputs, **inputs})

5. main.py에서 Flow 정의하기

크루를 Flow에 연결합니다. @start() 단계는 state에 주제를 설정하고, @listen 단계는 크루를 실행합니다. 태스크의 output_file은 여전히 output/report.md에 기록합니다.

# src/latest_ai_flow/main.py
from pydantic import BaseModel

from crewai.flow import Flow, listen, start

from latest_ai_flow.crews.content_crew.content_crew import kickoff_content_crew

class ResearchFlowState(BaseModel):
  topic: str = ""
  report: str = ""

class LatestAiFlow(Flow[ResearchFlowState]):
  @start()
  def prepare_topic(self, crewai_trigger_payload: dict | None = None):
    if crewai_trigger_payload:
      self.state.topic = crewai_trigger_payload.get("topic", "AI Agents")
    else:
      self.state.topic = "AI Agents"
    print(f"Topic: {self.state.topic}")

  @listen(prepare_topic)
  def run_research(self):
    result = kickoff_content_crew(inputs={"topic": self.state.topic})
    self.state.report = result.raw
    print("Research crew finished.")

  @listen(run_research)
  def summarize(self):
    print("Report path: output/report.md")

def kickoff():
  LatestAiFlow().kickoff()

def plot():
  LatestAiFlow().plot()

if __name__ == "__main__":
  kickoff()

패키지 이름이 latest_ai_flow와 다르다면, kickoff_content_crew import를 프로젝트의 모듈 경로에 맞게 바꿔주세요.

6. 환경 변수 설정하기

프로젝트 루트의 .env에 다음을 설정합니다:

• SERPER_API_KEY — Serper.dev에서 발급
• 필요에 따라 모델 프로바이더 키 — 참고: LLM 설정

7. 설치하고 실행하기

crewai install
crewai run

crewai run은 프로젝트에 정의된 Flow 진입점(entrypoint)을 실행합니다 (크루와 동일한 명령이며, pyproject.toml에서 프로젝트 타입은 "flow"입니다).

8. 출력 확인하기

Flow와 크루의 로그가 보일 거예요. 생성된 리포트는 **output/report.md**를 열어 확인하세요 (일부 발췌):

# AI Agents: Recent Landscape and Trends

## Executive summary
…

## Key trends
- **Tool use and orchestration** — …
- **Enterprise adoption** — …

## Implications
…

실제 파일은 더 길고, 실시간 검색 결과를 반영할 거예요.

이 실행이 어떻게 맞물리는지 (How this run fits together)

• Flow — LatestAiFlow는 먼저 prepare_topic을 실행하고, 그다음 run_research, 마지막으로 summarize를 실행합니다. 상태(topic, report)는 Flow에 존재합니다.
• Crew — kickoff_content_crew는 crew.jsonc를 불러와 한 명의 에이전트로 하나의 태스크를 실행합니다. 연구자는 Serper로 웹을 검색한 뒤 구조화된 리포트를 작성합니다.
• Artifact — 태스크의 output_file이 리포트를 output/report.md 아래에 기록합니다.

Flow 패턴에 대해 더 깊이 알아보려면(라우팅, 영속화, human-in-the-loop) Build your first Flow와 Flows를 확인하세요. Flow 없이 크루만 사용하려면 Crews를, 태스크 없이 단일 Agent와 kickoff()를 사용하려면 Agents를 참고하세요.

이제 에이전트 크루와 저장된 리포트를 갖춘 end-to-end Flow가 완성됐어요. 여기에 단계·크루·도구를 더 추가하기 좋은 탄탄한 기반이 됩니다.

이름 일관성 (Naming consistency)

crew.jsonc의 이름은 사용하는 파일과 태스크 참조와 일치해야 해요:

• agents: ["researcher"] → agents/researcher.jsonc 로드
• tasks[].agent: "researcher" → 태스크를 해당 에이전트에 배정

배포하기 (Deploying)

로컬에서 실행되고 프로젝트가 GitHub 저장소에 있으면, Flow를 **CrewAI AMP**에 푸시할 수 있어요. 프로젝트 루트에서 다음 명령을 사용합니다:

• 인증: crewai login
• 배포 생성: crewai deploy create
• 상태 & 로그 확인: crewai deploy status, crewai deploy logs
• 코드 변경 후 수정본 배포: crewai deploy push
• 배포 목록/제거: crewai deploy list, crewai deploy remove <deployment_id>

첫 배포는 보통 약 1분 정도 걸립니다. 전체 사전 조건과 웹 UI 흐름은 Deploy to AMP에서 확인할 수 있어요.

더 알아보기 (Learn more)

• Build your first Flow — Flow 패턴(라우팅, 영속화, human-in-the-loop)을 더 깊이 다루는 가이드
• Flows — CrewAI Flow의 핵심 개념 문서