main.py, Crew, Flow 또는 팩터리 함수가 필요하지 않습니다.
프로젝트 만들기
Terminal
openai/gpt-6.1-sol를 사용하도록 .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.yaml을 편집합니다:
messages로 전달하세요. 정의에 고정된 input 필드를 추가하지 마세요.
JSON 또는 Python 선택하기
Terminal
agent.json을 생성합니다:
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을 설정해 하나를 선택하세요.
사용자 지정 도구 추가하기
포함된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 전용 프로비저닝, 프로덕션 컨테이너 및 릴리스 호환성은 검증된 범위에 포함되지 않습니다.