--- title: "배포 준비하기" description: "Crew 또는 Flow가 CrewAI AMP에 배포될 준비가 되었는지 확인하기" icon: "clipboard-check" mode: "wide" --- CrewAI AMP에 배포하기 전에, 프로젝트가 올바르게 구성되어 있는지 확인하는 것이 중요합니다. Crews와 Flows 모두 "자동화"로 배포할 수 있지만, 성공적인 배포를 위해 충족해야 하는 서로 다른 프로젝트 구조와 요구 사항이 있습니다. ## 자동화 이해하기 CrewAI AMP에서 **자동화(automations)**는 배포 가능한 Agentic AI 프로젝트의 총칭입니다. 자동화는 다음 중 하나일 수 있습니다: - **Crew**: 작업을 함께 수행하는 AI 에이전트들의 독립 실행형 팀 - **Flow**: 여러 crew, 직접 LLM 호출 및 절차적 로직을 결합할 수 있는 오케스트레이션된 워크플로우 배포하는 유형을 이해하는 것은 프로젝트 구조와 진입점이 다르기 때문에 필수적입니다. ## Crews vs Flows: 주요 차이점 독립 실행형 AI 에이전트 팀입니다. 새 crew는 `crew.jsonc`와 `agents/`를 사용하는 JSON-first 구조이며, 클래식 crew는 계속 `crew.py`를 사용할 수 있습니다. `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: 도구 ├── 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]` 섹션이 포함되어야 합니다: ```toml [tool.crewai] type = "crew" ``` ```toml [tool.crewai] type = "flow" ``` `type`이 프로젝트 구조와 일치하지 않으면 빌드가 실패하거나 자동화가 올바르게 실행되지 않습니다. ### 2. uv.lock 파일 존재 확인 CrewAI는 의존성 관리를 위해 `uv`를 사용합니다. `uv.lock` 파일은 재현 가능한 빌드를 보장하며 배포에 **필수**입니다. ```bash # lock 파일 생성 또는 업데이트 uv lock # 존재 여부 확인 ls -la uv.lock ``` 파일이 존재하지 않으면 `uv lock`을 실행하고 저장소에 커밋하세요: ```bash 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 이름을 참조해야 합니다. ```jsonc 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:"`으로 참조하며, `tools/.py`에 `BaseTool` 서브클래스로 구현해야 합니다. 클래식 crew와 Flow 안에 포함된 Python crew는 `@CrewBase` 데코레이터를 사용해야 합니다. ```python 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 진입점을 사용합니다: 프로젝트 루트에서 로컬 실행합니다: ```bash crewai run ``` 진입점은 `run()` 함수를 사용합니다: ```python # 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()` 함수를 사용합니다: ```python # 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. 환경 변수 준비 배포 전에 다음을 준비해야 합니다: 1. **LLM API 키** (OpenAI, Anthropic, Google 등) 2. **도구 API 키** - 외부 도구를 사용하는 경우 (Serper 등) 프로젝트가 **프라이빗 PyPI 레지스트리**의 패키지에 의존하는 경우, 레지스트리 인증 자격 증명도 환경 변수로 구성해야 합니다. 자세한 내용은 [프라이빗 패키지 레지스트리](/ko/enterprise/guides/private-package-registry) 가이드를 참조하세요. 구성 문제를 조기에 발견하기 위해 배포 전에 동일한 환경 변수로 로컬에서 프로젝트를 테스트하세요. ## 빠른 검증 명령어 프로젝트 루트에서 다음 명령어를 실행하여 설정을 빠르게 확인하세요: ```bash # 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()` 누락 | 자동화를 시작할 수 없음 | 올바른 진입 함수 추가 | ## 다음 단계 프로젝트가 모든 체크리스트 항목을 통과하면 배포할 준비가 된 것입니다: CLI, 웹 인터페이스 또는 CI/CD 통합을 사용하여 Crew 또는 Flow를 CrewAI AMP에 배포하려면 배포 가이드를 따르세요.