메인 콘텐츠로 건너뛰기
CrewAI AMP에 배포하기 전에, 프로젝트가 올바르게 구성되어 있는지 확인하는 것이 중요합니다. Crews와 Flows 모두 “자동화”로 배포할 수 있지만, 성공적인 배포를 위해 충족해야 하는 서로 다른 프로젝트 구조와 요구 사항이 있습니다.

자동화 이해하기

CrewAI AMP에서 **자동화(automations)**는 배포 가능한 Agentic AI 프로젝트의 총칭입니다. 자동화는 다음 중 하나일 수 있습니다:
  • Crew: 작업을 함께 수행하는 AI 에이전트들의 독립 실행형 팀
  • Flow: 여러 crew, 직접 LLM 호출 및 절차적 로직을 결합할 수 있는 오케스트레이션된 워크플로우
배포하는 유형을 이해하는 것은 프로젝트 구조와 진입점이 다르기 때문에 필수적입니다.

Crews vs Flows: 주요 차이점

Crew 프로젝트

독립 실행형 AI 에이전트 팀입니다. 새 crew는 crew.jsoncagents/를 사용하는 JSON-first 구조이며, 클래식 crew는 계속 crew.py를 사용할 수 있습니다.

Flow 프로젝트

crews/ 폴더에 포함된 crew가 있는 오케스트레이션된 워크플로우. 복잡한 다단계 프로세스에 적합합니다.
측면CrewFlow
프로젝트 구조프로젝트 루트의 crew.jsoncagents/crews/ 폴더가 있는 src/project_name/
메인 로직 위치crew.jsonc (클래식: src/project_name/crew.py)src/project_name/main.py (Flow 클래스)
진입점 함수crew.jsonc에서 로드됨 (클래식: main.pyrun())main.pykickoff()
pyproject.toml 타입type = "crew"type = "flow"
CLI 생성 명령어crewai create crew namecrewai 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 구조를 얻습니다:
my_crew/
├── .gitignore
├── pyproject.toml          # type = "crew"여야 함
├── README.md
├── .env
├── uv.lock                  # 배포에 필수
├── crew.jsonc               # Crew 설정, 태스크, 프로세스, 입력
├── agents/
│   └── researcher.jsonc     # 에이전트 정의
├── tools/                   # 선택적 custom:<name> 도구
├── knowledge/
└── skills/
JSON-first crew에서는 crew.jsonc, agents/, tools/, knowledge/, skills/를 프로젝트 루트에 두세요. 이를 src/ 아래에 두면 crewai run과 배포 검증이 crew 정의를 찾지 못합니다.
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를 실행하면 다음 구조를 얻습니다:
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
JSON-first 독립 실행형 crew는 프로젝트 루트의 JSON 파일을 사용합니다. Flow는 여전히 src/project_name/을 사용하며, 클래식 포함 crew나 crewai.project.load_crew로 로드하는 포함 JSON crew 폴더를 둘 수 있습니다.

배포 전 체크리스트

이 체크리스트를 사용하여 프로젝트가 배포 준비가 되었는지 확인하세요.

1. pyproject.toml 설정 확인

pyproject.toml에 올바른 [tool.crewai] 섹션이 포함되어야 합니다:
[tool.crewai]
type = "crew"
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. Crew 정의 검증

JSON-first crew는 프로젝트 루트에 crew.jsonc 또는 crew.json 파일이 있어야 합니다. agents 배열은 agents/ 안의 파일을 참조해야 하며, 각 task는 유효한 agent 이름을 참조해야 합니다.
crew.jsonc
{
  "name": "Research Crew",
  "agents": ["researcher"],
  "tasks": [
    {
      "name": "research_task",
      "description": "Research {topic}.",
      "expected_output": "A concise report.",
      "agent": "researcher"
    }
  ],
  "inputs": {
    "topic": "AI Agents"
  }
}
커스텀 도구는 "custom:<name>"으로 참조하며, tools/<name>.pyBaseTool 서브클래스로 구현해야 합니다.

4. 프로젝트 진입점 확인

JSON-first 독립 실행형 crew는 직접 작성한 src/project_name/main.py가 필요하지 않습니다. crewai run과 배포 패키징이 crew.jsonc를 직접 로드합니다. 클래식 crew와 Flow는 Python 진입점을 사용합니다:
프로젝트 루트에서 로컬 실행합니다:
crewai run

5. 환경 변수 준비

배포 전에 다음을 준비해야 합니다:
  1. LLM API 키 (OpenAI, Anthropic, Google 등)
  2. 도구 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. JSON-first crew의 경우 crew.jsonc와 agents/ 확인
([ -f crew.jsonc ] || [ -f crew.json ]) || echo "crew.jsonc 또는 crew.json을 찾을 수 없습니다"
test -d agents || echo "agents/ 디렉터리를 찾을 수 없습니다"

# 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. 클래식 Python crews의 경우 - CrewBase 사용 확인
grep -r "@CrewBase" . --include="*.py"

일반적인 설정 실수

실수증상해결 방법
uv.lock 누락의존성 해결 중 빌드 실패uv lock 실행 후 커밋
pyproject.toml의 잘못된 type빌드 성공하지만 런타임 실패올바른 타입으로 변경
JSON-first crew에서 crew.jsonc 또는 agents/ 누락Crew 정의를 찾을 수 없음crew.jsoncagents/를 프로젝트 루트에 둠
클래식 crew에서 @CrewBase 데코레이터 누락”Config not found” 오류모든 클래식 crew 클래스에 데코레이터 추가
클래식 파일을 src/ 대신 루트에 배치진입점을 찾을 수 없음클래식 Python 파일을 src/project_name/으로 이동
run() 또는 kickoff() 누락자동화를 시작할 수 없음올바른 진입 함수 추가

다음 단계

프로젝트가 모든 체크리스트 항목을 통과하면 배포할 준비가 된 것입니다:

AMP에 배포하기

CLI, 웹 인터페이스 또는 CI/CD 통합을 사용하여 Crew 또는 Flow를 CrewAI AMP에 배포하려면 배포 가이드를 따르세요.