배포 준비하기

자동화 이해하기

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 구조를 얻습니다:

my_crew/
├── .gitignore
├── pyproject.toml          # type = "crew"여야 함
├── README.md
├── .env
├── uv.lock                  # 배포에 필수
├── crew.jsonc               # Crew 설정, 태스크, 프로세스, 입력
├── agents/
│   └── researcher.jsonc     # 에이전트 정의
├── tools/                   # 선택적 custom:<name> 도구
├── knowledge/
└── skills/

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

배포 전 체크리스트

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

1. pyproject.toml 설정 확인

pyproject.toml에 올바른 [tool.crewai] 섹션이 포함되어야 합니다:

Crews의 경우

[tool.crewai]
type = "crew"

Flows의 경우

[tool.crewai]
type = "flow"

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 Crews

JSON-first crew는 프로젝트 루트에 crew.jsonc 또는 crew.json 파일이 있어야 합니다. agents 배열은 agents/ 안의 파일을 참조해야 하며, 각 task는 유효한 agent 이름을 참조해야 합니다.

{
  "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>.py에 BaseTool 서브클래스로 구현해야 합니다.

클래식 Python/YAML Crews

클래식 crew와 Flow 안에 포함된 Python crew는 @CrewBase 데코레이터를 사용해야 합니다.

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,
        )

4. 프로젝트 진입점 확인

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

JSON-first Crews

프로젝트 루트에서 로컬 실행합니다:

crewai run

클래식 Crews

진입점은 run() 함수를 사용합니다:

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()

Flows의 경우

진입점은 Flow 클래스와 함께 kickoff() 함수를 사용합니다:

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 등)

빠른 검증 명령어

프로젝트 루트에서 다음 명령어를 실행하여 설정을 빠르게 확인하세요:

# 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.jsonc`와 `agents/`를 프로젝트 루트에 둠
클래식 crew에서 `@CrewBase` 데코레이터 누락	”Config not found” 오류	모든 클래식 crew 클래스에 데코레이터 추가
클래식 파일을 `src/` 대신 루트에 배치	진입점을 찾을 수 없음	클래식 Python 파일을 `src/project_name/`으로 이동
`run()` 또는 `kickoff()` 누락	자동화를 시작할 수 없음	올바른 진입 함수 추가

다음 단계

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

AMP에 배포하기

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