CrewAI AMP에 배포하기 전에, 프로젝트가 올바르게 구성되어 있는지 확인하는 것이 중요합니다.
Crews와 Flows 모두 “자동화”로 배포할 수 있지만, 성공적인 배포를 위해 충족해야 하는
서로 다른 프로젝트 구조와 요구 사항이 있습니다.
자동화 이해하기
CrewAI AMP에서 **자동화(automations)**는 배포 가능한 Agentic AI 프로젝트의 총칭입니다. 자동화는 다음 중 하나일 수 있습니다:
- Crew: 작업을 함께 수행하는 AI 에이전트들의 독립 실행형 팀
- Flow: 여러 crew, 직접 LLM 호출 및 절차적 로직을 결합할 수 있는 오케스트레이션된 워크플로우
배포하는 유형을 이해하는 것은 프로젝트 구조와 진입점이 다르기 때문에 필수적입니다.
Crews vs Flows: 주요 차이점
Crew 프로젝트
에이전트와 작업을 정의하는 crew.py가 있는 독립 실행형 AI 에이전트 팀. 집중적이고 협업적인 작업에 적합합니다.
Flow 프로젝트
crews/ 폴더에 포함된 crew가 있는 오케스트레이션된 워크플로우. 복잡한 다단계 프로세스에 적합합니다.
| 측면 | Crew | Flow |
|---|
| 프로젝트 구조 | crew.py가 있는 src/project_name/ | crews/ 폴더가 있는 src/project_name/ |
| 메인 로직 위치 | src/project_name/crew.py | src/project_name/main.py (Flow 클래스) |
| 진입점 함수 | main.py의 run() | main.py의 kickoff() |
| pyproject.toml 타입 | type = "crew" | type = "flow" |
| CLI 생성 명령어 | crewai create crew name | crewai create flow name |
| 설정 위치 | src/project_name/config/ | src/project_name/crews/crew_name/config/ |
| 다른 crew 포함 가능 | 아니오 | 예 (crews/ 폴더 내) |
프로젝트 구조 참조
Crew 프로젝트 구조
crewai create crew my_crew를 실행하면 다음 구조를 얻습니다:
my_crew/
├── .gitignore
├── pyproject.toml # type = "crew"여야 함
├── README.md
├── .env
├── uv.lock # 배포에 필수
└── src/
└── my_crew/
├── __init__.py
├── main.py # run() 함수가 있는 진입점
├── crew.py # @CrewBase 데코레이터가 있는 Crew 클래스
├── tools/
│ ├── custom_tool.py
│ └── __init__.py
└── config/
├── agents.yaml # 에이전트 정의
└── tasks.yaml # 작업 정의
중첩된 src/project_name/ 구조는 Crews에 매우 중요합니다.
잘못된 레벨에 파일을 배치하면 배포 실패의 원인이 됩니다.
Flow 프로젝트 구조
crewai create flow my_flow를 실행하면 다음 구조를 얻습니다:
my_flow/
├── .gitignore
├── pyproject.toml # type = "flow"여야 함
├── README.md
├── .env
├── uv.lock # 배포에 필수
└── src/
└── my_flow/
├── __init__.py
├── main.py # kickoff() 함수 + Flow 클래스가 있는 진입점
├── crews/ # 포함된 crews 폴더
│ └── poem_crew/
│ ├── __init__.py
│ ├── poem_crew.py # @CrewBase 데코레이터가 있는 Crew
│ └── config/
│ ├── agents.yaml
│ └── tasks.yaml
└── tools/
├── __init__.py
└── custom_tool.py
Crews와 Flows 모두 src/project_name/ 구조를 사용합니다.
핵심 차이점은 Flows는 포함된 crews를 위한 crews/ 폴더가 있고,
Crews는 프로젝트 폴더에 직접 crew.py가 있다는 것입니다.
배포 전 체크리스트
이 체크리스트를 사용하여 프로젝트가 배포 준비가 되었는지 확인하세요.
1. pyproject.toml 설정 확인
pyproject.toml에 올바른 [tool.crewai] 섹션이 포함되어야 합니다:
[tool.crewai]
type = "crew"
[tool.crewai]
type = "flow"
type이 프로젝트 구조와 일치하지 않으면 빌드가 실패하거나
자동화가 올바르게 실행되지 않습니다.
2. uv.lock 파일 존재 확인
CrewAI는 의존성 관리를 위해 uv를 사용합니다. uv.lock 파일은 재현 가능한 빌드를 보장하며 배포에 필수입니다.
# lock 파일 생성 또는 업데이트
uv lock
# 존재 여부 확인
ls -la uv.lock
uv lock을 실행하고 저장소에 커밋하세요:
uv lock
git add uv.lock
git commit -m "Add uv.lock for deployment"
git push
3. CrewBase 데코레이터 사용 확인
모든 crew 클래스는 @CrewBase 데코레이터를 사용해야 합니다. 이것은 다음에 적용됩니다:
- 독립 실행형 crew 프로젝트
- Flow 프로젝트 내에 포함된 crews
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase # 이 데코레이터는 필수입니다
class MyCrew():
"""내 crew 설명"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def my_agent(self) -> Agent:
return Agent(
config=self.agents_config['my_agent'], # type: ignore[index]
verbose=True
)
@task
def my_task(self) -> Task:
return Task(
config=self.tasks_config['my_task'] # type: ignore[index]
)
@crew
def crew(self) -> Crew:
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
@CrewBase 데코레이터를 잊으면 에이전트나 작업 구성이 누락되었다는
오류와 함께 배포가 실패합니다.
4. 프로젝트 진입점 확인
Crews와 Flows 모두 src/project_name/main.py에 진입점이 있습니다:
진입점은 run() 함수를 사용합니다:# src/my_crew/main.py
from my_crew.crew import MyCrew
def run():
"""crew를 실행합니다."""
inputs = {'topic': 'AI in Healthcare'}
result = MyCrew().crew().kickoff(inputs=inputs)
return result
if __name__ == "__main__":
run()
진입점은 Flow 클래스와 함께 kickoff() 함수를 사용합니다:# src/my_flow/main.py
from crewai.flow import Flow, listen, start
from my_flow.crews.poem_crew.poem_crew import PoemCrew
class MyFlow(Flow):
@start()
def begin(self):
# Flow 로직
result = PoemCrew().crew().kickoff(inputs={...})
return result
def kickoff():
"""flow를 실행합니다."""
MyFlow().kickoff()
if __name__ == "__main__":
kickoff()
5. 환경 변수 준비
배포 전에 다음을 준비해야 합니다:
- LLM API 키 (OpenAI, Anthropic, Google 등)
- 도구 API 키 - 외부 도구를 사용하는 경우 (Serper 등)
프로젝트가 프라이빗 PyPI 레지스트리의 패키지에 의존하는 경우, 레지스트리 인증 자격 증명도
환경 변수로 구성해야 합니다. 자세한 내용은
프라이빗 패키지 레지스트리 가이드를 참조하세요. 구성 문제를 조기에 발견하기 위해 배포 전에 동일한 환경 변수로
로컬에서 프로젝트를 테스트하세요.
빠른 검증 명령어
프로젝트 루트에서 다음 명령어를 실행하여 설정을 빠르게 확인하세요:
# 1. pyproject.toml에서 프로젝트 타입 확인
grep -A2 "\[tool.crewai\]" pyproject.toml
# 2. uv.lock 존재 확인
ls -la uv.lock || echo "오류: uv.lock이 없습니다! 'uv lock'을 실행하세요"
# 3. src/ 구조 존재 확인
ls -la src/*/main.py 2>/dev/null || echo "src/에서 main.py를 찾을 수 없습니다"
# 4. Crews의 경우 - crew.py 존재 확인
ls -la src/*/crew.py 2>/dev/null || echo "crew.py가 없습니다 (Crews에서 예상됨)"
# 5. Flows의 경우 - crews/ 폴더 존재 확인
ls -la src/*/crews/ 2>/dev/null || echo "crews/ 폴더가 없습니다 (Flows에서 예상됨)"
# 6. CrewBase 사용 확인
grep -r "@CrewBase" . --include="*.py"
일반적인 설정 실수
| 실수 | 증상 | 해결 방법 |
|---|
uv.lock 누락 | 의존성 해결 중 빌드 실패 | uv lock 실행 후 커밋 |
pyproject.toml의 잘못된 type | 빌드 성공하지만 런타임 실패 | 올바른 타입으로 변경 |
@CrewBase 데코레이터 누락 | ”Config not found” 오류 | 모든 crew 클래스에 데코레이터 추가 |
src/ 대신 루트에 파일 배치 | 진입점을 찾을 수 없음 | src/project_name/으로 이동 |
run() 또는 kickoff() 누락 | 자동화를 시작할 수 없음 | 올바른 진입 함수 추가 |
다음 단계
프로젝트가 모든 체크리스트 항목을 통과하면 배포할 준비가 된 것입니다:
AMP에 배포하기
CLI, 웹 인터페이스 또는 CI/CD 통합을 사용하여 Crew 또는 Flow를 CrewAI AMP에
배포하려면 배포 가이드를 따르세요.
