CrewAI AMP에 배포하기 전에, 프로젝트가 올바르게 구성되어 있는지 확인하는 것이 중요합니다.
Crews와 Flows 모두 “자동화”로 배포할 수 있지만, 성공적인 배포를 위해 충족해야 하는
서로 다른 프로젝트 구조와 요구 사항이 있습니다.
자동화 이해하기
CrewAI AMP에서 **자동화(automations)**는 배포 가능한 Agentic AI 프로젝트의 총칭입니다. 자동화는 다음 중 하나일 수 있습니다:- Crew: 작업을 함께 수행하는 AI 에이전트들의 독립 실행형 팀
- Flow: 여러 crew, 직접 LLM 호출 및 절차적 로직을 결합할 수 있는 오케스트레이션된 워크플로우
Crews vs Flows: 주요 차이점
Crew 프로젝트
독립 실행형 AI 에이전트 팀입니다. 새 crew는
crew.jsonc와 agents/를 사용하는 JSON-first 구조이며, 클래식 crew는 계속 crew.py를 사용할 수 있습니다.Flow 프로젝트
crews/ 폴더에 포함된 crew가 있는 오케스트레이션된 워크플로우. 복잡한 다단계 프로세스에 적합합니다.| 측면 | Crew | Flow |
|---|---|---|
| 프로젝트 구조 | 프로젝트 루트의 crew.jsonc와 agents/ | crews/ 폴더가 있는 src/project_name/ |
| 메인 로직 위치 | crew.jsonc (클래식: src/project_name/crew.py) | src/project_name/main.py (Flow 클래스) |
| 진입점 함수 | crew.jsonc에서 로드됨 (클래식: main.py의 run()) | main.py의 kickoff() |
| pyproject.toml 타입 | type = "crew" | type = "flow" |
| CLI 생성 명령어 | crewai create crew name | crewai create flow name |
| 설정 위치 | crew.jsonc, agents/, 선택적 tools/ | src/project_name/crews/crew_name/config/ 또는 포함된 JSON crew 폴더 |
| 다른 crew 포함 가능 | 아니오 | 예 (crews/ 폴더 내) |
프로젝트 구조 참조
Crew 프로젝트 구조
crewai create crew my_crew를 실행하면 JSON-first 구조를 얻습니다:
crewai create crew my_crew --classic으로 만든 클래식 프로젝트는 기존
src/project_name/crew.py, src/project_name/config/agents.yaml,
src/project_name/config/tasks.yaml 구조를 사용합니다. 이 구조는 decorator 기반 Python crew를 위해 계속 지원됩니다.Flow 프로젝트 구조
crewai create flow my_flow를 실행하면 다음 구조를 얻습니다:
JSON-first 독립 실행형 crew는 프로젝트 루트의 JSON 파일을 사용합니다.
Flow는 여전히
src/project_name/을 사용하며, 클래식 포함 crew나
crewai.project.load_crew로 로드하는 포함 JSON crew 폴더를 둘 수 있습니다.배포 전 체크리스트
이 체크리스트를 사용하여 프로젝트가 배포 준비가 되었는지 확인하세요.1. pyproject.toml 설정 확인
pyproject.toml에 올바른 [tool.crewai] 섹션이 포함되어야 합니다:
- Crews의 경우
- Flows의 경우
2. uv.lock 파일 존재 확인
CrewAI는 의존성 관리를 위해uv를 사용합니다. uv.lock 파일은 재현 가능한 빌드를 보장하며 배포에 필수입니다.
uv lock을 실행하고 저장소에 커밋하세요:
3. Crew 정의 검증
- JSON-first Crews
- 클래식 Python/YAML Crews
JSON-first crew는 프로젝트 루트에 커스텀 도구는
crew.jsonc 또는 crew.json 파일이 있어야 합니다.
agents 배열은 agents/ 안의 파일을 참조해야 하며, 각 task는 유효한 agent 이름을 참조해야 합니다.crew.jsonc
"custom:<name>"으로 참조하며, tools/<name>.py에 BaseTool 서브클래스로 구현해야 합니다.4. 프로젝트 진입점 확인
JSON-first 독립 실행형 crew는 직접 작성한src/project_name/main.py가 필요하지 않습니다.
crewai run과 배포 패키징이 crew.jsonc를 직접 로드합니다. 클래식 crew와 Flow는 Python 진입점을 사용합니다:
- JSON-first Crews
- 클래식 Crews
- Flows의 경우
프로젝트 루트에서 로컬 실행합니다:
5. 환경 변수 준비
배포 전에 다음을 준비해야 합니다:- LLM API 키 (OpenAI, Anthropic, Google 등)
- 도구 API 키 - 외부 도구를 사용하는 경우 (Serper 등)
프로젝트가 프라이빗 PyPI 레지스트리의 패키지에 의존하는 경우, 레지스트리 인증 자격 증명도
환경 변수로 구성해야 합니다. 자세한 내용은
프라이빗 패키지 레지스트리 가이드를 참조하세요.
빠른 검증 명령어
프로젝트 루트에서 다음 명령어를 실행하여 설정을 빠르게 확인하세요:일반적인 설정 실수
| 실수 | 증상 | 해결 방법 |
|---|---|---|
uv.lock 누락 | 의존성 해결 중 빌드 실패 | uv lock 실행 후 커밋 |
pyproject.toml의 잘못된 type | 빌드 성공하지만 런타임 실패 | 올바른 타입으로 변경 |
JSON-first crew에서 crew.jsonc 또는 agents/ 누락 | Crew 정의를 찾을 수 없음 | crew.jsonc와 agents/를 프로젝트 루트에 둠 |
클래식 crew에서 @CrewBase 데코레이터 누락 | ”Config not found” 오류 | 모든 클래식 crew 클래스에 데코레이터 추가 |
클래식 파일을 src/ 대신 루트에 배치 | 진입점을 찾을 수 없음 | 클래식 Python 파일을 src/project_name/으로 이동 |
run() 또는 kickoff() 누락 | 자동화를 시작할 수 없음 | 올바른 진입 함수 추가 |
다음 단계
프로젝트가 모든 체크리스트 항목을 통과하면 배포할 준비가 된 것입니다:AMP에 배포하기
CLI, 웹 인터페이스 또는 CI/CD 통합을 사용하여 Crew 또는 Flow를 CrewAI AMP에
배포하려면 배포 가이드를 따르세요.
