main.py, Crew, Flow 또는 팩터리 함수가 필요하지 않습니다.
프로젝트 만들기
Terminal
openai/gpt-6-luna를 사용하도록 .env에 OPENAI_API_KEY를 설정한 다음 설치하고 실행합니다:
스캐폴드는 이 모델의 도구 호출에 Responses API(api: responses)를 사용합니다. YAML/JSON 프로젝트에서는 정의 파일의 llm.model과 llm.api를 수정하세요. Python 템플릿은 .env에서 MODEL을 읽고 Responses API를 사용합니다.
Terminal
crewai install은 uv.lock을 생성합니다. 이 파일을 프로젝트와 함께 커밋하세요. .env는 로컬에 보관하고, 공급자 인증 정보는 배포 환경 설정에 지정하세요.
로컬 대화
스캐폴드는conversational: true를 설정하며 Python에서는 Agent(conversational=True)를 사용합니다. 터미널에서 crewai run을 실행하면 기존 대화형 채팅 인터페이스가 열립니다. 각 메시지는 설정된 Agent와 도구에 세션 기록을 전달합니다. 독립적인 kickoff만 사용하려면 플래그를 false로 설정하세요.
Terminal
agent.handle_turn(...)과 agent.as_flow()로 같은 세션을 제공합니다. 기록은 기본적으로 메모리에 유지되며, 프로세스 간 복구를 위해서는 Flow 영속성을 명시적으로 설정해야 합니다. 독립적인 대화마다 별도의 Agent 인스턴스를 사용하세요. session_id 옵션은 Flow 세션을 식별하거나 복원하며 하나의 Agent를 동시 다중 세션 서버로 만들지는 않습니다.
프로젝트 구조
pyproject.toml은 Agent 정의를 선택하고 설정과 로컬 도구를 패키지에 포함합니다:
Agent 정의하기
기본 정체성은 범용 CrewAI Agent입니다.role, goal, backstory를 편집해 특화할 수 있습니다. 포함된 지원 도구는 관련이 있을 때만 사용하는 예시이므로 다른 용도에서는 교체하거나 제거하세요. 기본으로 설치된 스킬은 없습니다.
agent.json을 편집합니다:
messages로 전달하세요. 정의에 고정된 input 필드를 추가하지 마세요.
YAML 또는 Python 선택하기
Terminal
agent.yaml을 생성합니다:
src/python_support/agent.py에서 agent = Agent(...)를 내보냅니다. Agent를 정의하는 데 Python 로직이 필요한 경우 사용하세요.
.yml과 .yaml을 모두 지원합니다. 설정 파일의 이름이나 위치를 변경할 때는 definition과 wheel의 only-include 목록을 함께 수정하세요. 정의 경로는 프로젝트 루트 안에 있어야 합니다.
definition을 명시하지 않으면 루트의 agent.py, agent.json, agent.yml, agent.yaml 또는 일반적인 src/<package>/agent.py 중 하나를 검색합니다. 여러 파일이 발견되면 오류가 발생하므로 definition을 설정해 하나를 선택하세요.
CLI로 도구 추가하기
터미널에서 JSON 또는 YAML 프로젝트에 대해crewai create agent를 실행하면 CrewAI Platform 애플리케이션을 포함하여 crewai create crew와 동일한 도구 선택기가 열립니다. 나중에 도구를 더 추가하려면 프로젝트에서 crewai tool add를 실행하고, 선택기에서 고르거나 이름으로 지정하세요:
Terminal
tools 목록에 도구를 추가하고, 도구에 필요한 경우 crewai 의존성을 crewai[tools]로 변경합니다. 그런 다음 crewai install을 실행하세요. CrewAI Platform 애플리케이션은 추가되기 전에 AMP에서 검증되며, Enterprise Action Auth Token은 .env에 저장됩니다. 프로젝트를 클론한 후처럼 정의에 이미 있는 플랫폼 애플리케이션을 검증하려면 crewai tool setup을 실행하세요. Python Agent는 대신 agent.py에서 편집합니다.
사용자 지정 도구 추가하기
포함된tools/support_hours.py를 새 도구의 출발점으로 사용하세요:
custom:support_hours는 tools/support_hours.py에서 BaseTool 하위 클래스를 로드합니다. 도구에 필요한 의존성을 pyproject.toml에 추가하고 crewai install로 잠금 파일을 갱신하세요. 신뢰할 수 있는 프로젝트 코드만 로드하세요. 사용자 지정 도구와 Python 참조는 로딩 중 Python 코드를 실행합니다.
참조 도구와 스킬
생성된 예제는 로컬의 가상 데이터를 사용합니다. 실제 계정을 조회하거나 비밀번호를 재설정하거나 환불하거나 티켓을 만들지 않습니다.skills/ 디렉터리는 Git과 빌드된 패키지에서 유지하기 위한 .gitkeep만 포함하며 비어 있습니다. 스킬을 만들려면 name과 description 프런트매터를 포함한 skills/<name>/SKILL.md를 추가하세요. 추가된 스킬은 메타데이터로 검색되며 Agent는 load_skill로 관련 지침을 필요할 때 로드할 수 있습니다.
YAML/JSON의 로컬 스킬 경로는 프로젝트 루트를 기준으로 해석됩니다. 다른 디렉터리에서 load_agent_project(path)를 호출해도 동일합니다. Python 스캐폴드는 tools/와 skills/를 모두 src/<package>/ 안에 두고 agent.py를 기준으로 스킬 경로를 지정합니다. wheel과 배포 아카이브에 이 파일들이 포함됩니다.
예제 기능을 함께 사용하는 요청을 실행해 보세요:
Terminal
메시지 기록 전달하기
messages는 role/content 메시지로 구성된 비어 있지 않은 목록도 받습니다:
Terminal
미리 보기 검증 및 배포하기
Terminal
.env와 .venv를 제외하고 정의, 도구, 스킬 및 잠금 파일을 포함합니다.
호환되는 미리 보기 Enterprise 런타임에 배포하려면 CLI 참조에 설명된 기존 배포 절차를 사용하세요. 관리형 API는 동일한 입력을 받습니다:
대화형 관리형 배포
호환되는 실험적 Enterprise 런타임에서 내부 Agent 어댑터는conversational = True를 설정합니다. 채팅은 매 턴마다 설정된 Agent와 도구를 사용합니다. 세션을 시작한 뒤 후속 메시지에 같은 session_id를 사용하세요:
kickoff_id를 반환합니다. 다음 메시지를 보내기 전에 /status/<kickoff_id>를 조회하여 턴이 완료될 때까지 기다리세요. 세션은 사용자/어시스턴트 기록을 보존하고 매 턴 새 Agent에 전달합니다. 대화 기록에는 사용자에게 보여 줄 답변만 포함되며, 실행 결과에는 구조화된 Agent 출력과 사용량이 유지됩니다. 세션 수명과 영속성은 배포된 런타임의 저장소 설정에 따라 달라집니다. 세션별 기록은 분리됩니다.
POST /kickoff는 독립적인 실행에 계속 사용할 수 있습니다. 로컬 crewai run은 채팅을 열고 crewai run --inputs는 kickoff를 한 번 실행합니다. 스캐폴드는 Agent 정의에서 대화 플래그를 활성화하므로 Flow나 main.py를 작성할 필요가 없습니다.
이 미리 보기는 네이티브 API와 Celery 워커로 검증되었습니다. 토큰 스트리밍, 복원/체크포인트 지원, Agent 전용 프로비저닝, 프로덕션 컨테이너 및 릴리스 호환성은 검증된 범위에 포함되지 않습니다.