Update installation and quickstart documentation for JSON-first crew projects

- Revised the installation guide to reflect the new JSON-first project structure, detailing the creation of `crew.jsonc` and `agents/*.jsonc` files. - Updated the quickstart guide to demonstrate setting up agents and tasks using JSONC format, replacing previous YAML examples. - Enhanced the agents and tasks documentation to clarify the transition from YAML to JSONC, including examples and explanations of the new structure. - Added notes on the classic YAML structure for legacy projects and provided guidance on migrating to the new format.
2026-07-29 02:29:31 +00:00 · 2026-06-16 08:28:37 -07:00
parent e9d568dc69
commit 5b766f999f
60 changed files with 2022 additions and 2814 deletions
--- a/docs/ko/enterprise/features/secrets-manager/verify-rotation.mdx
+++ b/docs/ko/enterprise/features/secrets-manager/verify-rotation.mdx
@@ -26,10 +26,10 @@ icon: "arrows-rotate"

 ## 1단계 — 검증 Crew 스캐폴딩

-새 Crew 프로젝트를 만듭니다. CrewAI CLI가 구조를 스캐폴딩합니다:
+이 예제는 `crew.py`를 통해 Python 도구를 연결하므로 클래식 crew 프로젝트를 만듭니다:

 ```bash
-crewai create crew rotation_verifier --skip_provider
+crewai create crew rotation_verifier --classic --skip_provider
 cd rotation_verifier
 ```

--- a/docs/ko/enterprise/guides/deploy-to-amp.mdx
+++ b/docs/ko/enterprise/guides/deploy-to-amp.mdx
@@ -373,17 +373,17 @@ git push

 **해결책**: 프로젝트가 예상 구조와 일치하는지 확인합니다:

- **Crews와 Flows 모두**: 진입점이 `src/project_name/main.py`에 있어야 합니다
- **Crews**: 진입점으로 `run()` 함수 사용
- **Flows**: 진입점으로 `kickoff()` 함수 사용
+- **JSON-first Crews**: `crew.jsonc` 또는 `crew.json`과 `agents/`를 프로젝트 루트에 둡니다
+- **클래식 Crews**: `src/project_name/main.py`에 `run()` 진입점을 둡니다
+- **Flows**: `src/project_name/main.py`에 `kickoff()` 진입점을 둡니다

 자세한 구조 다이어그램은 [배포 준비하기](/ko/enterprise/guides/prepare-for-deployment)를 참조하세요.

-#### CrewBase 데코레이터 누락
+#### 클래식 Crew의 CrewBase 데코레이터 누락

 **증상**: "Crew not found", "Config not found" 또는 agent/task 구성 오류

-**해결책**: **모든** crew 클래스가 `@CrewBase` 데코레이터를 사용하는지 확인합니다:
+**해결책**: 클래식 Python/YAML crew에서는 모든 crew 클래스가 `@CrewBase` 데코레이터를 사용하는지 확인합니다. JSON-first crew에는 이 데코레이터가 필요하지 않습니다.

 ```python
 from crewai.project import CrewBase, agent, crew, task
@@ -403,8 +403,8 @@ class YourCrew():
 ```

 <Info>
-  이것은 독립 실행형 Crews와 Flow 프로젝트 내에 포함된 crews 모두에 적용됩니다.
-  모든 crew 클래스에 데코레이터가 필요합니다.
+  이것은 Flow 프로젝트에 포함된 클래식 crew를 포함하여 클래식 Python crew 클래스에 적용됩니다.
+  JSON-first crew는 `crew.jsonc`와 `agents/`를 기준으로 검증됩니다.
 </Info>

 #### 잘못된 pyproject.toml 타입
@@ -441,8 +441,8 @@ type = "flow"
 **해결책**:
 1. AMP 대시보드에서 실행 로그를 확인합니다 (Traces 탭)
 2. 모든 도구에 필요한 API 키가 구성되어 있는지 확인합니다
-3. `agents.yaml`의 agent 구성이 유효한지 확인합니다
-4. `tasks.yaml`의 task 구성에 구문 오류가 없는지 확인합니다
+3. JSON-first crew의 경우 `crew.jsonc`와 `agents/`에서 참조한 파일을 검증합니다
+4. 클래식 crew의 경우 `agents.yaml`과 `tasks.yaml`이 유효한지 확인합니다

 <Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
  배포 문제 또는 AMP 플랫폼에 대한 문의 사항이 있으시면 지원팀에 연락해 주세요.
--- a/docs/ko/enterprise/guides/monorepo-deployments.mdx
+++ b/docs/ko/enterprise/guides/monorepo-deployments.mdx
@@ -24,10 +24,9 @@ company-ai/
 `-- crews/
    |-- support_agent/
    |   |-- pyproject.toml
-    |   `-- src/
-    |       `-- support_agent/
-    |           |-- main.py
-    |           `-- crew.py
+    |   |-- crew.jsonc
+    |   `-- agents/
+    |       `-- support_agent.jsonc
    `-- research_flow/
        |-- pyproject.toml
        `-- src/
@@ -48,7 +47,7 @@ AMP는 여전히 전체 저장소를 가져오거나 업로드하지만, 선택

 작업 디렉터리가 설정되면 AMP는 해당 폴더를 다음 용도로 사용합니다:

- `pyproject.toml`, `src/`, Crew 또는 Flow 진입점을 포함한 프로젝트 검증
+- `pyproject.toml`, JSON crew 파일, 클래식 Crew 또는 Flow 진입점을 포함한 프로젝트 검증
 - `uv`를 사용한 종속성 설치
 - 실행 중인 프로세스의 작업 디렉터리
 - `CREW_ROOT_DIR` 환경 변수
--- a/docs/ko/enterprise/guides/prepare-for-deployment.mdx
+++ b/docs/ko/enterprise/guides/prepare-for-deployment.mdx
@@ -24,7 +24,7 @@ CrewAI AMP에서 **자동화(automations)**는 배포 가능한 Agentic AI 프

 <CardGroup cols={2}>
  <Card title="Crew 프로젝트" icon="users">
-    에이전트와 작업을 정의하는 `crew.py`가 있는 독립 실행형 AI 에이전트 팀. 집중적이고 협업적인 작업에 적합합니다.
+    독립 실행형 AI 에이전트 팀입니다. 새 crew는 `crew.jsonc`와 `agents/`를 사용하는 JSON-first 구조이며, 클래식 crew는 계속 `crew.py`를 사용할 수 있습니다.
  </Card>
  <Card title="Flow 프로젝트" icon="diagram-project">
    `crews/` 폴더에 포함된 crew가 있는 오케스트레이션된 워크플로우. 복잡한 다단계 프로세스에 적합합니다.
@@ -33,19 +33,19 @@ CrewAI AMP에서 **자동화(automations)**는 배포 가능한 Agentic AI 프

 | 측면 | 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()` |
+| **프로젝트 구조** | 프로젝트 루트의 `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` |
-| **설정 위치** | `src/project_name/config/` | `src/project_name/crews/crew_name/config/` |
+| **설정 위치** | `crew.jsonc`, `agents/`, 선택적 `tools/` | `src/project_name/crews/crew_name/config/` 또는 포함된 JSON crew 폴더 |
 | **다른 crew 포함 가능** | 아니오 | 예 (`crews/` 폴더 내) |

 ## 프로젝트 구조 참조

 ### Crew 프로젝트 구조

-`crewai create crew my_crew`를 실행하면 다음 구조를 얻습니다:
+`crewai create crew my_crew`를 실행하면 JSON-first 구조를 얻습니다:

 ```
 my_crew/
@@ -54,24 +54,25 @@ my_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   # 작업 정의
+├── crew.jsonc               # Crew 설정, 태스크, 프로세스, 입력
+├── agents/
+│   └── researcher.jsonc     # 에이전트 정의
+├── tools/                   # 선택적 custom:<name> 도구
+├── knowledge/
+└── skills/
 ```

 <Warning>
-  중첩된 `src/project_name/` 구조는 Crews에 매우 중요합니다.
-  잘못된 레벨에 파일을 배치하면 배포 실패의 원인이 됩니다.
+  JSON-first crew에서는 `crew.jsonc`, `agents/`, `tools/`, `knowledge/`, `skills/`를
+  프로젝트 루트에 두세요. 이를 `src/` 아래에 두면 `crewai run`과 배포 검증이 crew 정의를 찾지 못합니다.
 </Warning>

+<Info>
+  `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를 위해 계속 지원됩니다.
+</Info>
+
 ### Flow 프로젝트 구조

 `crewai create flow my_flow`를 실행하면 다음 구조를 얻습니다:
@@ -100,9 +101,9 @@ my_flow/
 ```

 <Info>
-  Crews와 Flows 모두 `src/project_name/` 구조를 사용합니다.
-  핵심 차이점은 Flows는 포함된 crews를 위한 `crews/` 폴더가 있고,
-  Crews는 프로젝트 폴더에 직접 `crew.py`가 있다는 것입니다.
+  JSON-first 독립 실행형 crew는 프로젝트 루트의 JSON 파일을 사용합니다.
+  Flow는 여전히 `src/project_name/`을 사용하며, 클래식 포함 crew나
+  `crewai.project.load_crew`로 로드하는 포함 JSON crew 폴더를 둘 수 있습니다.
 </Info>

 ## 배포 전 체크리스트
@@ -154,60 +155,88 @@ git commit -m "Add uv.lock for deployment"
 git push
 ```

-### 3. CrewBase 데코레이터 사용 확인
+### 3. Crew 정의 검증

-**모든 crew 클래스는 `@CrewBase` 데코레이터를 사용해야 합니다.** 이것은 다음에 적용됩니다:
+<Tabs>
+  <Tab title="JSON-first Crews">
+    JSON-first crew는 프로젝트 루트에 `crew.jsonc` 또는 `crew.json` 파일이 있어야 합니다.
+    `agents` 배열은 `agents/` 안의 파일을 참조해야 하며, 각 task는 유효한 agent 이름을 참조해야 합니다.

- 독립 실행형 crew 프로젝트
- Flow 프로젝트 내에 포함된 crews
+    ```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"
+      }
+    }
+    ```

-```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
+    커스텀 도구는 `"custom:<name>"`으로 참조하며, `tools/<name>.py`에 `BaseTool` 서브클래스로 구현해야 합니다.
+  </Tab>
+  <Tab title="클래식 Python/YAML Crews">
+    클래식 crew와 Flow 안에 포함된 Python crew는 `@CrewBase` 데코레이터를 사용해야 합니다.

-@CrewBase  # 이 데코레이터는 필수입니다
-class MyCrew():
-    """내 crew 설명"""
+    ```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

-    agents: List[BaseAgent]
-    tasks: List[Task]
+    @CrewBase
+    class MyCrew():
+        """내 crew 설명"""

-    @agent
-    def my_agent(self) -> Agent:
-        return Agent(
-            config=self.agents_config['my_agent'],  # type: ignore[index]
-            verbose=True
-        )
+        agents: List[BaseAgent]
+        tasks: List[Task]

-    @task
-    def my_task(self) -> Task:
-        return Task(
-            config=self.tasks_config['my_task']  # type: ignore[index]
-        )
+        @agent
+        def my_agent(self) -> Agent:
+            return Agent(
+                config=self.agents_config['my_agent'],  # type: ignore[index]
+                verbose=True
+            )

-    @crew
-    def crew(self) -> Crew:
-        return Crew(
-            agents=self.agents,
-            tasks=self.tasks,
-            process=Process.sequential,
-            verbose=True,
-        )
-```
+        @task
+        def my_task(self) -> Task:
+            return Task(
+                config=self.tasks_config['my_task']  # type: ignore[index]
+            )

-<Warning>
-  `@CrewBase` 데코레이터를 잊으면 에이전트나 작업 구성이 누락되었다는
-  오류와 함께 배포가 실패합니다.
-</Warning>
+        @crew
+        def crew(self) -> Crew:
+            return Crew(
+                agents=self.agents,
+                tasks=self.tasks,
+                process=Process.sequential,
+                verbose=True,
+            )
+    ```
+  </Tab>
+</Tabs>

 ### 4. 프로젝트 진입점 확인

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

 <Tabs>
-  <Tab title="Crews의 경우">
+  <Tab title="JSON-first Crews">
+    프로젝트 루트에서 로컬 실행합니다:
+
+    ```bash
+    crewai run
+    ```
+  </Tab>
+  <Tab title="클래식 Crews">
    진입점은 `run()` 함수를 사용합니다:

    ```python
@@ -278,16 +307,17 @@ 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를 찾을 수 없습니다"
+# 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 존재 확인
+# 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 사용 확인
+# 6. 클래식 Python crews의 경우 - CrewBase 사용 확인
 grep -r "@CrewBase" . --include="*.py"
 ```

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

 ## 다음 단계