agentcad
AI 에이전트를 위한 CAD 도구입니다. 코딩 에이전트에게 3D 모델을 설계할 수 있는 능력을 부여합니다.
에이전트는 기본적으로 build123d Python 스크립트를 작성합니다. agentcad는 실행, STEP 내보내기(export), PNG 렌더링, 메시 내보내기(mesh export) (STL/GLB/OBJ), 기하학적 측정 지표(geometric metrics), 유효성 검사(validation), 차이점 비교(diffing), 브라우저 미리보기 등을 처리합니다. CadQuery는 명시적인 호환성 모드(compatibility mode)로 계속 사용할 수 있습니다. 각 명령어의 최종 응답은 stdout에 구조화된 JSON 형식으로 출력됩니다.
출력 읽기: JSON 응답은 stdout에 작성되며, 사람이 읽을 수 있는 진행 상황 및 진단 정보는 stderr로 전송됩니다. JSON 파서 이전에 stdout을 JSON으로 파싱하고 stderr를 일반 텍스트로 처리하십시오. 2>&1을 사용하여 스트림을 병합하면 진행 상황 라인이 파싱을 방해할 수 있습니다. 두 가지가 모두 필요하다면, 각각 별도로 캡처해야 합니다.
agentcad는 Apache License 2.0에 따라 오픈 소스입니다. 로컬에서 실행되며 가입(signup)이 필요 없습니다.
Featured on Product Hunt
데모
Watch a coding agent design in agentcad
coding agent가 agentcad에서 설계하는 모습을 실시간으로 확인하세요. 더 많은 내용은 agentcad.dev에서 확인하십시오.
CADGenBench에서: 48% 높은 CAD 점수 및 21.8% 낮은 모델 비용
Watch measuring agentcad's effectiveness
GPT-5 Nano 비교에서, agentcad를 사용하는 에이전트는 2.5배 더 많은 유효한 출력을 생성했습니다. 비디오를 시청하거나, 벤치마크 결과를 읽거나, 또는 더 최신 업데이트를 보려면 변경 로그(change log)를 확인하십시오.
v0.7.0 릴리스에는 아래의 5단계 워크플로우가 설치된 가이드 및 내장 도움말에 포함되었습니다. Candidate L CADGenBench 실행에서 GPT-5 Nano는 전체적으로 .245(생성 .175, 편집 .353)를 기록했으며 유효 출력 81개 중 80개를 달성했습니다. 이는 새로운 매칭된 직접 빌드 비교가 아닌 단일 실행 결과이므로, 기준선, 주의사항 및 다음 평가에 대해서는 실험 종료를 참조하십시오.
빠른 시작 (Quick start)
agentcad를 설치한 후, 이 내용을 Claude Code, Cursor 또는 모든 코딩 에이전트에 붙여넣으십시오:
Create a Python 3.12 virtual environment, then:
pip install agentcad
...
재사용 가능한 에이전트 스킬을 별도로 설치하려면 다음 명령어를 사용하십시오.
npx skills add jdilla1277/agentcad-skill 또는 clawhub install agentcad.
두 명령어 모두 CAD 실행 파일이 아닌 가이드만 설치합니다. 따라서 위에서 보여준 대로 pip으로 agentcad를 설치하십시오. 프로젝트 로컬 가이드가 필요하면 대신 agentcad skill install을 실행하십시오.
생성된 파일을 빌드 디렉터리에 보관하기 (Keep generated files in a build directory)
초기화 전에 소스 프로젝트에 agentcad.toml을 생성하십시오:
그런 다음 agentcad init을 실행하십시오. 버전 디렉터리, 생성된 매니페스트(manifest), 뷰어, 내보내기 파일 및 로그는 build/ 아래에 저장되며, 작성된 스크립트와 설치된 가이드는 소스 프로젝트에 유지됩니다. 빌드 디렉터리를 자체 .gitignore에 추가하십시오.
CI 환경에서 독립적인 루트를 초기화하고 선택하려면 agentcad init --build-dir /tmp/cad-build 및 agentcad run model.py --label first --build-dir /tmp/cad-build를 사용합니다. 오버라이드는 프로젝트 구성을 편집하지 않습니다. 상대 빌드 경로는 호출자의 작업 디렉터리가 아닌 프로젝트 루트에서 해결됩니다. 기존 프로젝트는 구성되지 않는 한 현재 레이아웃을 유지합니다. --output은 여전히 사용 중단된 버전 라벨이며, 결코 목적지가 아닙니다. 전체 계약 내용은 agentcad docs artifacts를 참조하십시오.
필수 에이전트 워크플로우
agentcad init은 새 모델 및 편집에 동일한 워크플로우를 요구하는 가이드를 설치합니다:
검사(Inspect) → 명세화(Specify) → 빌드(Build) → 검증(Validate) → 전달(Deliver)
- 검사(Inspect): 모델을 작성하기 전에 도면, 요구 사항, 방향, 치수 및 모든 소스 지오메트리를 이해합니다.
- 명세화(Specify): 측정 가능한 요구 사항과 가정을 기록합니다. 편집의 경우, 대상, 예상 변경 사항 및 안정적으로 유지되어야 하는 지오메트리도 식별합니다.
- 빌드(Build): 명세를 만족시킬 수 있는 가장 단순한 지오메트리를 생성하며, 편집을 위해서는 가장 작은 경계 연산(bounded operation)을 사용합니다.
- 검증(Validate): 시각적, 치수적, 차이점, 구조적 증거를 검사합니다. 확인에 실패하면 가장 초기의 잘못된 단계로 돌아가 반복합니다.
- 전달(Deliver): 통과한 정확한 STEP 및 요청된 내보내기(export)만 전달합니다.
워크플로우 단계별 기능
검사(Inspect)
agentcad inspect output.step — 경계 토폴로지(bounded topology), 방향, 주소 지정 가능 ID, 편집 위험 및 구조적 증거agentcad measure output.step — 치수, 모서리 길이, 면적, 그리고 원형/원통형 특징 측정값agentcad render output.step --view top,front,right,iso — 방향 및 특징 위치에 대한 시각적 증거agentcad parts list REF / parts show REF ID — 명명된 부품을 검사하고 버전 관리된 하나의 부품을 격리합니다.
명세화(Specify)
spec.json — 모델링 전에 지원되는 원통형 피처 및 구조 요구 사항을 기록합니다.agentcad check-spec output.step spec.json — 검증 과정에서 해당 계약(contract)을 평가합니다.
Build
agentcad run script.py --label label — build123d 스크립트를 실행하여 버전이 지정된 STEP 파일과 기하학적 메트릭(geometric metrics)을 생성합니다.- 사전 주입된 헬퍼 기능 (Pre-injected helpers) — 기본 프리미티브를 구축하고, 기존 STEP 지오메트리를 가져오며, 피처를 선택하고, 경계가 지정되거나 검증된 편집 작업을 수행합니다.
Validate
agentcad run ... --preview — 시각적 검증을 위한 4뷰(four-view) PNG를 제공하며, 브라우저 뷰어에서 요청 시 회전하는 터너테이블 GIF를 내보낼 수 있습니다.agentcad diff 1 2 — 버전을 비교하며, 유효한 폐쇄 솔리드(closed solids)에 대한 실제 공유/참조 전용/후보 전용 소스 프레임 볼륨을 포함합니다.agentcad view old.step new.step — 별도의 중앙 투영(centered projection) 및 소스 프레임 3D 볼륨 아티팩트와 함께 동기화된 A/B 비교를 열어줍니다.- 실시간 프로젝트 뷰어 (Live project viewer) — 성공적인 실행은 하나의 안정적인 로컬 프로젝트 URL을 열고 후속 빌드가 완료된 후 이를 새로 고칩니다. 반복 작업 시 탭을 열어두세요. 카메라 및 호환 가능한 검토 설정은 업데이트를 거치면서 유지됩니다. 실패한 빌드는 마지막으로 성공한 모델을 보이게 합니다. 버전이 지정된
viewer.html 스냅샷은 계속 사용할 수 있습니다. v2부터는 이전 버전과 현재 버전을 나란히 비교, 오버레이(overlay), 그리고 Parts 탭 변경 검토를 위해 사전 로드됩니다 (--no-view 옵션 사용 시 제외).
- 공간 검토 댓글 (Spatial review comments) — 표면 및 명명된 부품에 인간의 피드백을 고정(pin)합니다. 댓글은 에이전트의 다음 개정을 위해 로컬에 유지됩니다.
agentcad review list --status open — 공유된 검토 스레드를 읽습니다. 인간과 에이전트는 감사 가능한 기록(auditable history)을 가지고 답장하고, 해결하고, 다시 열 수 있습니다.agentcad parts view REF — 격리되거나, 초점이 맞추어졌거나, 그룹화된 부품 검토 뷰어를 전달합니다.
Deliver
agentcad run ... --export stl,glb 또는 agentcad export — 메시 결과물 작성 및 각 작성 형식에 대한 유효성 보고서 제공agentcad viewer [open|status|stop] — 라이브 프로젝트를 열거나 경량 로컬 서비스를 관리합니다. open이 기본값입니다.agentcad docs [section] — 런타임 인지 내장 문서 및 실습 예제
실행 후 또는 agentcad viewer open을 사용하여 열린 라이브 프로젝트 뷰어는 127.0.0.1에 바인딩된 기존 서비스를 사용합니다. 왼쪽 하단 뷰어 컨트롤에서 Comments를 클릭한 다음, + 새 의견 작성(또는 C 누르기)을 클릭합니다. 모델을 클릭하고 추론된 명명된 부품 및 개정 범위를 확인한 다음, **의견 전송(Send comment)**을 선택합니다. 피드백을 보류하려면 대신 **초안 저장(Save draft)**을 선택하십시오. 전송되지 않은 초안은 수정하거나 삭제할 수 있으며, 개별적으로 전송하거나 **모든 초안 전송(Send all drafts)**과 함께 제출할 수 있습니다.
의견은 선택된 빌드 루트의 .agentcad/reviews 아래에 있는 일반 로컬 JSON 파일입니다. 데이터베이스나 호스팅 계정은 없습니다. 다음 차례에 에이전트는 검토 내용을 발견하고 답장할 수 있습니다:
agentcad context
agentcad review list --status open
agentcad review comment --message "Could this rib be thinner?" --part support_rib --version current
...
에이전트는 또한 명명된 부품에 대해 즉시 열리는 스레드를 시작할 수도 있습니다. 비교 대상 측면을 지정하려면 --scope previous|both를 추가하거나, 핀 위치를 더 정확하게 배치하려면 --point-mm X,Y,Z를 사용하십시오. 인간과 에이전트 모두 답장하고, 해결(resolve)하거나, 다시 열 수 있습니다. 모든 동작은 행위자(actor), 타임스탬프, 선택적 메시지 및 관련 개정본을 기록합니다. 이전의 mark-addressed 명령어는 호환성을 위해 계속 사용할 수 있습니다.
새로운 빌드는 댓글을 작성하거나 전송할 때, 또는 답장을 보낼 때 대기하며, 보내거나 저장하거나 취소한 후에 모델이 업데이트됩니다. 현재/이전/모두(Current/Previous/Both)는 표시된 수정 버전 측면을 따르며, 원본 소스 버전은 스레드에 유지됩니다. 부품이 사라지면 해당 댓글은 '배치되지 않음(unplaced)' 상태로 목록에 남아 있습니다. 부품을 숨기면 3D 뷰에서 해당 부품의 댓글 핀이 숨겨지고, 스레드는 사이드바에 남아 있습니다. 부품을 표시하면 핀이 복원됩니다. 댓글은 에이전트가 다음 차례(next turn)에 사용할 수 있게 되며, 새로운 에이전트 실행을 시작하지는 않습니다.
파일 뷰어 및 임시 부품/차이점(diff) 뷰어는 읽기 전용 상태로 유지됩니다.
모델의 위치를 재조정하려면 Pan을 클릭하고 드래그하거나, Shift를 누른 채 드래그합니다. 다시 Pan을 클릭하면 오비팅(orbiting)으로 돌아갑니다. Fit view는 보이는 모델을 중앙에 배치하고 화면에 맞게 확대/축소됩니다.
--label은 버전을 이름 짓고, JSON 응답은 실제 파일을 outputs.step 아래에서 반환합니다. 이전의 --output LABEL 표기는 사용 중단된 호환성 별칭으로 남아 있으며, 결코 목적지 경로를 나타내지 않습니다.
미리보기 하나 열어두기
정상적인 run 또는 import 후에는 사용자에게 JSON 응답에서 project_viewer.url을 제공하십시오. 이 URL은 가장 최근에 완료된 뷰어를 추적하며, viewer는 여전히 해당 버전의 스냅샷을 가리킵니다. 활성화된 페이지는 다른 브라우저 탭이 열리는 것을 방지합니다. 업데이트 확인은 약 1초 간격으로 이루어집니다(백그라운드 탭에서는 더 자주 일어나지 않습니다). 새로운 모델은 성공적으로 로드된 후에만 이전 모델을 대체합니다.
--no-view는 브라우저를 열거나 뷰어 서비스를 시작하지 않습니다. 그럼에도 불구하고 뷰어 아티팩트가 생성되는 경우, 이미 열려 있는 프로젝트 페이지가 이를 받을 수 있습니다. 핵심 기능만을 사용하는 --no-preview --no-diff --no-view 조합은 뷰어를 생성하지 않으며, 페이지는 이전 모델을 유지하고 새로운 미리보기가 사용 불가능하다고 보고합니다.
이 서비스는 127.0.0.1에 바인딩되며 등록된 뷰어 스냅샷만 비공개 프로젝트 URL에서 제공합니다. 이는 공개 공유 링크가 아닌 로컬 북마크입니다. URL은 서비스 재시작 및 빌드를 거치더라도 유지되지만, 프로젝트 폴더를 이동하면 식별자가 변경됩니다. 뷰어 상태는 ~/.cache/agentcad/viewer에 저장되며 (격리된 자동화를 위해 AGENTCAD_VIEWER_HOME으로 오버라이드 가능), 저장된 포트와 비공개 URL을 보존하려면 해당 디렉토리를 유지해야 합니다. 포트가 사용 중인 경우, AgentCAD는 URL을 조용히 변경하는 대신 문제를 보고합니다. 진단에는 agentcad viewer status와 agentcad viewer stop을 사용하고; agentcad viewer open으로 재시작할 수 있습니다. 호환되지 않는 서비스 프로토콜은 해당 서비스를 시작한 설치본으로 서비스를 중지시킨 후 새 설치본으로 다시 열어야 합니다.
보일러플레이트 없음 (No boilerplate)
스크립트는 임포트가 전혀 필요하지 않습니다. 기본적으로 build123d 프리미티브, show_object, 그리고 agentcad 편집 도우미 기능이 사전 주입됩니다:
box = Box(10, 20, 5)
show_object(box)
에디터 자동 완성 또는 명시적 종속성을 위해, 동일한 AgentCAD 소유의 호출 가능한 함수(callables)는 안정적인 작성 모듈에서 사용할 수 있습니다:
from agentcad.api import load_step, safe_cut, translate, show_object
Box나 Vector와 같은 build123d 프리미티브는 build123d 자체에서 임포트하세요. STEP 라이터(writers)는 임포트하지 마십시오: show_object가 결과를 AgentCAD에 반환하면, AgentCAD가 표준(canonical) STEP 파일을 작성하고 추적합니다.
build123d 스크립트에서는 show_object(), show_assembly(), 및 show_compound() 호출 전반과 어셈블리 반복 가능한(iterables) 내에서 각 형상 객체(shape object)를 단 한 번만 캡처해야 합니다. 어셈블리를 캡처하면 모든 자손(descendants)이 함께 캡처되므로, 자식 요소를 별도로 캡처하거나 다른 캡처된 어셈블리에서 재사용하지 마십시오. 반복 참조는 error_kind: "duplicate_capture" 오류로 실패합니다. 이름이나 ID를 변경해도 새로운 인스턴스가 생성되지 않습니다. 의도적인 인스턴스의 경우, from copy import deepcopy를 사용하여 위치 지정 및 캡처하기 전에 형상을 복사하십시오. 예시는 agentcad docs parts를 참조하십시오.
agentcad init은 build123d를 프로젝트 런타임으로 기록합니다. 이를 통해 스크립트 API(script API), 내장 문서(built-in docs), 그리고 후속 실행(subsequent runs)을 하나의 명확한 기본값에 유지할 수 있습니다.
