기본 콘텐츠로 건너뛰기

CrewAI Tutorial: Build Your First Multi-Agent Crew

Summary: CrewAI is an open-source framework for multi-agent teams (Crews) and stateful orchestration (Flows). This tutorial walks you from installing the CLI with uv, through a JSON-first two-agent research crew that writes a markdown report, to knowing when a Flow wrapper is worth adding. All install steps, agent files, and plan limits below are taken from CrewAI's official docs and pricing page as of 2026-11-05.

What CrewAI actually is: Crews plus Flows

CrewAI's own introduction describes the product as a framework for orchestrating autonomous AI agents and building complex workflows. The architecture has two pieces that work together rather than competing:

  • Flows are the backbone: structured, event-driven workflows with state management, conditional logic, loops, and branching. Think of a Flow as the process definition that decides what runs next.
  • Crews are the intelligence units: teams of role-playing agents that collaborate on a delegated task, with tools, goals, and task handoff.

In a typical production pattern, a Flow triggers, manages state, and hands a hard problem to a Crew. The Crew's agents finish the work and return a result; the Flow continues from there. You can run a Crew on its own for learning and prototypes. For anything that needs reliable sequencing, branching, or persistence, the docs recommend starting with a Flow and calling Crews from Flow steps.

A short decision frame from CrewAI's evaluating-use-cases guide: pick a Crew when you need collaborative, creative, or analytical work with some flexibility in the output shape; pick a Flow when you need precise control, structured state, conditional paths, or a mix of AI and ordinary Python. High-complexity, high-precision apps often use Flows that orchestrate multiple Crews with validation between steps. See the official screenshots at the end of this post for the Flows/Crews diagrams and the complexity-precision matrix.

Install the CrewAI CLI (uv first)

CrewAI requires Python >=3.10 and <3.14. Check with python3 --version before you install anything. The CLI is distributed through Astral's uv tool installer, not a bare pip install as the primary path in the current docs.

Step 1: Install uv

On macOS or Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

If curl is missing, the same script works with wget: wget -qO- https://astral.sh/uv/install.sh | sh.

On Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2: Install the crewai CLI

uv tool install crewai

If you get a PATH warning, run uv tool update-shell and open a new terminal. On Windows, a build error around chroma-hnswlib==0.7.6 complaining that float.h cannot be opened usually means you need Visual Studio Build Tools with the "Desktop development with C++" workload.

Confirm the tool is present:

uv tool list

You should see a crewai entry. Upgrade the global CLI later with uv tool install crewai --upgrade. That upgrades the CLI tool only; upgrading the package inside a project venv is a separate step covered in CrewAI's migration guide.

Optional but useful: CrewAI 0.175.0 expects openai >= 1.13.3 if you manage the OpenAI SDK yourself. Keep API keys out of git; the scaffolded projects put them in .env.

Build your first two-agent research crew (JSON-first)

New crew projects are JSON-first. Agents live in agents/*.jsonc, tasks and crew settings live in crew.jsonc, and crewai run loads that definition directly. If you still need the older crew.py plus YAML layout, add --classic when creating the project.

Prerequisites for this walkthrough

  1. CrewAI CLI installed as above.
  2. An LLM API key configured per the LLM setup guide (for example OPENAI_API_KEY, or whatever your chosen provider needs).
  3. A Serper.dev API key if the researcher should search the web (SERPER_API_KEY in .env). Without Serper, drop SerperDevTool from the agent tools list or the search step will fail.

Step 1: Scaffold the project

crewai create crew research_crew
cd research_crew

You get a tree roughly like this: .env, agents/researcher.jsonc, crew.jsonc, knowledge/, pyproject.toml, skills/, and tools/. File names under agents/ are the names you reference from crew.jsonc.

Step 2: Define researcher and analyst agents

Replace the generated researcher file and add an analyst. The official first-crew guide uses placeholders like {topic} and a model id such as openai/gpt-4o (or Anthropic / Gemini ids). Keep the model string in provider/model-id form.

Researcher (agents/researcher.jsonc): role focused on finding recent, accurate information; goal that stresses comprehensive notes; tools including "SerperDevTool" when you have a Serper key; settings.verbose true; allow_delegation false for a predictable two-step pipeline.

Analyst (agents/analyst.jsonc): role that turns findings into a clear report; no search tool required; same LLM field pattern; verbose on, delegation off.

You do not need to invent Python classes for this starter. JSONC is enough for the first run.

Step 3: Wire tasks in crew.jsonc

The crew file lists agents by name, then a tasks array. A minimal sequential research crew looks like this in spirit (match the official guide when you paste):

  • research_task assigned to researcher, with a description and expected_output that mention {topic}.
  • analysis_task assigned to analyst, with "context": ["research_task"] so the analyst receives the research output, plus "output_file": "output/report.md" and "markdown": true.
  • Crew-level "process": "sequential", "verbose": true, optional "memory": true, and an inputs object with a default topic such as "Artificial Intelligence in Healthcare".

If you remove a default from inputs, crewai run prompts for the missing placeholder at runtime. That is handy when you want to reuse the same crew for different topics without editing JSON every time.

Step 4: Environment variables, install, run

Put keys in .env:

SERPER_API_KEY=your_serper_api_key
# plus your model provider key, e.g. OPENAI_API_KEY=...

Then:

crewai install
crewai run

crewai install syncs the project environment. Extra packages go in with uv add <package-name>. After a successful run, open output/report.md. The flow of execution is: crew.jsonc defines order → researcher runs first → analyst runs with research context → final task writes the markdown file.

How to extend without rewriting everything

Add more agents as new agents/<name>.jsonc files and list them in crew.jsonc. Append tasks to the array. Built-in tools are referenced by class name strings such as "FileReadTool" or "SerperDevTool". Custom tools use "custom:<name>", which loads tools/<name>.py. Hierarchical process mode is available with "process": "hierarchical" plus a manager LLM or manager agent. Treat untrusted JSON crew projects carefully: custom tools and Python attribute references execute local Python when the crew loads.

Optional next step: wrap the crew in a Flow

Once a standalone crew works, the quickstart shows the production-shaped pattern: scaffold with crewai create flow latest-ai-flow, keep a small research crew under the Flow's crews/ tree, load it with load_crew, and drive it from a Flow class that holds state (topic, report) with @start() and @listen steps. The Flow owns execution order; the crew does the agent work; the task's output_file still writes output/report.md.

You still run with crewai install and crewai run — the project type in pyproject.toml tells the CLI it is a Flow. Deploying to CrewAI AMP after local success uses crewai login, crewai deploy create, then status/logs/push commands documented in the quickstart. Skip the full Flow code dump here; copy the official quickstart when you are ready, and keep agent/task names consistent between crew.jsonc and the agents/ filenames.

If you are choosing architecture for a larger app, CrewAI's complexity-versus-precision matrix is worth a careful read: simple creative work can stay on a small Crew; data extraction with strict schemas often wants a Flow with structured outputs; enterprise pipelines usually combine both. Related reading on our blog: the Dify playbook for turning help docs into an AI assistant and the n8n AI agent error fixes cover neighbouring orchestration styles.

Open-source CLI vs CrewAI AMP Free vs Enterprise

The open-source path is local: you install the CLI, bring your own LLM keys, and run crews or flows on your machine. CrewAI AMP is the hosted platform (sign up at app.crewai.com). Pricing below is only what appears on the official pricing page and installation notes — no invented dollar amounts.

Capability Open-source CLI CrewAI AMP Free Enterprise (Custom)
How you get it uv tool install crewai; Python >=3.10 and <3.14; local project with your own LLM API keys Sign up at app.crewai.com; no local install required for the hosted studio path Sales / request trial; custom pricing
Build experience JSON-first (or classic) projects in your editor; crewai create / crewai run Visual editor and AI copilot; GitHub integration Everything in Free, plus enterprise connectors and governance features
Executions / scale Limited by your machine and provider quotas 50 workflow executions per month (Free plan also lists 50 as the maximum) Sized to workflow; flexible overage
Deployment Your laptop / your servers CrewAI cloud CrewAI cloud, your VPC, or your own infrastructure
Security & onboarding You own keys, network, and secrets Community support path on Free SSO, RBAC, workload identity, PII redaction, and policies; 45-day onboarding; forward-deployed engineering and training available a la carte

Free also lists private agent/tool repositories, templates, tracing, OpenTelemetry, guardrails, human-in-the-loop, and workflow chat in the comparison grid on the pricing page. Enterprise adds dedicated support channels, training, and on-site options that Free marks as unavailable. Treat the table as a shopping map, then confirm live limits on crewai.com/pricing before you commit a team budget.

Editor's note

Who this is for: developers who want a real multi-agent research or report pipeline on their own machine, and teams evaluating whether AMP's visual editor is enough before buying Enterprise governance. Who this is not for: people who need a no-code chatbot UI only, or who expect the framework to include free LLM calls — open-source CrewAI always brings your own provider keys.

Gotchas from the official docs:

  • After uv tool install crewai, a PATH warning means run uv tool update-shell (or fix PATH manually) before crewai is found.
  • Windows chroma-hnswlib builds that fail on missing float.h need Visual Studio Build Tools with C++ desktop development.
  • JSON crews that use custom:<name> tools or Python attribute references execute local Python on load — only run projects from sources you trust.
  • Python must be >=3.10 and <3.14; outside that range the install path will fight you.
  • The first-crew and quickstart tutorials that call SerperDevTool need SERPER_API_KEY; missing it is a common silent failure for "web research" demos.

If your local LLM stack misbehaves while you debug CrewAI, our AnythingLLM troubleshooting guide covers a related desktop/Docker chat stack that often sits next to the same provider keys.

FAQ

Q: Is the open-source CrewAI free?
A: Yes — the open-source framework and CLI are free to install and run locally. You still pay your LLM provider (and Serper if you use web search). CrewAI AMP Free is a separate hosted tier with a visual editor, GitHub integration, and 50 workflow executions per month. Enterprise is custom-priced.

Q: Do I need a Serper API key?
A: Only if an agent lists SerperDevTool (as in the official first-crew and quickstart tutorials). Without web search you can omit that tool, or swap in other built-in tools such as file readers, and rely on the model's knowledge alone. Put SERPER_API_KEY in .env when you do use Serper.

Q: Crew vs Flow — which should I start with?
A: Start with a Crew if you want the fastest path to a collaborating multi-agent pipeline (this tutorial). Start with a Flow when you need state, branching, or production structure around that crew. CrewAI's introduction says production apps usually use both: Flow as the manager, Crew as the team that does the hard collaborative work.

Install with uv, define two JSONC agents, wire sequential tasks with context and an output file, then run — that is the shortest honest path to a working CrewAI crew. Official diagrams from the documentation are at the end of this post.

Image credit: Official diagrams from the CrewAI documentation (docs.crewai.com); CrewAI pricing page screenshot captured 2026-11-05.

Last verified: 2026-11-05
Sources: Installation, Build your first crew, Quickstart, Introduction, LLMs, Evaluating use cases, Pricing, CrewAI AMP signup.

Uploaded Image Uploaded Image Uploaded Image Uploaded Image

댓글

이 블로그의 인기 게시물

브루(Vrew) 요금제 정리: 무료 200크레딧으로 어디까지 쓸 수 있나

요약: 영상 자막 편집기 브루(Vrew)는 2026년 4월 22일부터 기능별 사용량 대신 '통합 크레딧' 하나로 요금을 매겨요. 무료 플랜은 매달 200크레딧이 들어오는데, 음성 분석(자동 자막)만 쓰면 최대 200분 분량이라 짧은 영상 몇 편은 충분하지만, 영상 초반의 Vrew 마크를 지우려면 유료 플랜이 필요해요. 이 글은 브루 공식 가격 페이지와 고객센터 공지를 2026년 10월 23일에 다시 확인해, 크레딧 계산법과 플랜 고르는 기준을 정리했어요. 목차 브루 요금 구조: 통합 크레딧이란 1크레딧으로 할 수 있는 일 무료 플랜으로 되는 것과 안 되는 것 유료 플랜 4종 비교표 월 구독·연 구독·기간 이용권, 무엇이 이득일까 상황별 추천: 학생·직장인·유튜버 크레딧이 모자랄 때: 사용 기록 지우개 업그레이드·환불 전에 알아둘 규칙 운영자 메모, 자주 묻는 질문 1. 브루 요금 구조: 통합 크레딧이란 예전 브루는 플랜마다 음성 분석 몇 분, AI 목소리 몇 자, 번역 몇 자처럼 기능별 한도를 따로 줬어요. 그런데 보이저엑스(브루 운영사)가 실제 이용 데이터를 보니 한두 가지 기능만 집중해서 쓰는 사람이 훨씬 많았다고 해요. 그래서 2026년 4월 22일 업데이트부터는 플랜마다 정해진 크레딧을 받고, 어떤 기능에 쓸지는 내가 정하는 방식으로 바뀌었어요. 플랜별 매달 지급량은 Free 200 · Light 2,000 · Standard 10,000 · Business 12,000크레딧 이에요. 공식 공지에 따르면 무료 사용자는 매달 1일에, 유료 사용자는 매월 결제일에 충전되고, 남은 크레딧은 다음 달로 넘어가지 않아요. 바뀐 뒤 무엇이 좋아졌나 공지에 나온 예시가 이해하기 쉬워요. Standard 플랜에서 AI 목소리만 쓰면 예전에는 최대 50만 자였지만, 지금은 1만 크레딧을 모두 AI 목소리에 몰아 쓸 수 있어 최대 100만 자가 돼요. 반대로 여러 기능을 골고루 쓰는 사람은 크레딧이 기능끼리 ...

에이닷 전화 vs 익시오: 통화 녹음·AI 요약, 내 통신사·폰에 맞는 앱 고르기

요약: 통화 녹음과 AI 요약을 쓰고 싶다면 먼저 내 통신사와 휴대폰 종류부터 확인해야 해요. LG유플러스 고객은 무료 앱 익시오, SKT 고객은 에이닷 전화가 가장 기능이 많고, 다른 통신사의 아이폰 사용자는 iOS에 들어 있는 기본 통화 녹음·전사 기능이 현실적인 선택이에요. 이 글은 2026-10-30에 SKT·LG유플러스·Apple 공식 페이지와 도움말을 직접 확인해 세 가지를 비교했어요. 왜 '앱 기능'보다 '내 조건'을 먼저 봐야 할까요 통화 요약 앱 비교 글을 보면 기능 목록부터 나열하는 경우가 많아요. 그런데 실제로 써 보려는 사람에게 가장 먼저 걸리는 건 기능이 아니라 이용 조건 이에요. 익시오는 LG유플러스 고객 전용이고, 에이닷 전화는 누구나 설치할 수 있지만 통역콜·baro 같은 기능은 SKT 고객에게만 열려 있어요. 아이폰은 운영체제 구조상 앱이 통화를 마음대로 녹음하기 어려워서, 통신사 앱이 안 되면 iOS 기본 기능에 기대야 해요. 그래서 이 글은 "어떤 앱이 제일 좋은가"보다 "내 통신사·내 폰에서 무엇을 쓸 수 있나" 순서로 정리했어요. 기능 차이는 그다음이에요. 한눈에 비교: 에이닷 전화 vs 익시오 vs 아이폰 기본 통화 녹음 구분 에이닷 전화 (SKT) 익시오 ixi-O (LG유플러스) 아이폰 기본 통화 녹음 (Apple) 누가 쓸 수 있나 통신사 구분 없이 앱 설치 가능. 단, 통역콜·baro·그룹통화 발신 등은 SKT 고객 전용 U+ 모바일 고객. 타 통신사, 만 14세 미만, 선불요금제 고객은 제한 (공식 사이트 FAQ상 알뜰폰 중 KB리브엠은 예외) 지원 국가·언어의 iPhone 사용자. 1명과 통화할 때만 녹음 가능 지원 OS·기기 Android 10 이상, iOS 16 이상 iOS 17 이상 iPhone 12 이상 / Android...

타입캐스트 vs 클로바더빙: 수익 나는 채널에 쓸 때 무료·유료 조건 비교

요약 타입캐스트와 클로바더빙은 둘 다 글만 입력하면 한국어 AI 목소리를 만들어 주는 서비스지만, 무료로 쓸 수 있는 범위가 꽤 다릅니다. 클로바더빙 무료는 매달 15,000자까지 쓸 수 있는 대신 수익이 생기는 채널에는 쓸 수 없고, 타입캐스트 무료는 처음에 주는 약 5분 분량의 다운로드로 끝나는 체험판에 가깝습니다. 광고 수익이 붙은 유튜브나 쇼핑몰 영상에 넣을 목소리라면 처음부터 유료 플랜 조건을 보고 고르는 편이 안전합니다. 왜 이 두 서비스를 같이 비교하나 쇼츠 내레이션, 수업 자료 더빙, 상품 소개 영상처럼 "내 목소리 대신 AI 목소리"가 필요할 때 한국 사용자들이 가장 많이 찾는 곳이 네오사피엔스의 타입캐스트 와 네이버의 클로바더빙 입니다. 기능 소개만 보면 비슷해 보이지만, 실제로 문제가 되는 건 음질보다 "이 목소리를 내 채널에 써도 되나" 입니다. 그래서 이 글은 기능 나열보다 무료 사용 범위, 출처 표기 의무, 유료 플랜 가격과 다운로드 한도를 중심으로 정리했습니다. 모든 수치는 2026년 10월 25일에 두 서비스의 공식 요금 페이지와 고객센터 도움말에서 직접 다시 확인한 내용입니다. 한눈에 보는 비교표 항목 타입캐스트 무료 타입캐스트 베이직 클로바더빙 Free 클로바더빙 Standard 월 요금 0원 9,900원 (연간 결제 시 10% 할인) 0원 19,900원 (네이버 클라우드 플랫폼에서 결제) 무료·포함 사용량 음성 생성·재생 무제한, 다운로드는 최초 3,000크레딧(약 5분) 1회 지급 월 30,000크레딧(약 60분) 월 15,000자, 다운로드 월 20회, 프로젝트 누적 5개 (매월 1일 갱신) 월 30,000자, 다운로드 월 40회, 프로젝트 누적 20개 쓸 수 있...