짜는 법과 돌리는 법을 답하는 묶음입니다. 무엇을 부를 수 있는지(Zio.node · Zio.text · Zio.utils …)는 주제별 문서에 따로 있고, 여기서 다루는 것은 그 함수를 어디에 놓고 어떻게 돌리는가입니다. 어느 것을 쓰든 놓는 자리와 돌리는 길은 같습니다.
플랫폼의 .skills/ 디렉토리 안에 파이썬 스크립트를 작성하고 @zio_skill 데코레이터를 붙이면, 해당 함수는 skillFunction 노드이자 AI 도구로 등록됩니다. 플랫폼 전체를 내렸다 올릴 필요는 없습니다 — 그 스킬 하나만 다시 띄우면 됩니다(아래 「다시 띄우기」).
main.py는 작성할 필요 없습니다!
@zio_skill 함수만 작성하면, 플랫폼이 콜드 스타트 시 자동으로 main.py를 생성하고 가상환경(.venv)도 만듭니다. 둘 다 직접 만들지 마십시오.
main.py 가 하는 일은 둘뿐입니다 — @zio_skill 함수를 등록하는 것, 그리고 화면이 필요할 때 화면을 내주는 라우트.
호출되지 않았는데 스스로 일을 시작하는 코드는 넣지 않습니다 — startup 훅에서 루프를 켜거나, 스레드를 띄우거나, 기동할 때 바로 무언가를 호출하는 것. 스킬은 호출될 때 일하고 답을 돌려줍니다. 주기적으로 해야 할 일이 있으면, 그 일을 함수로 만들고 호출하는 쪽(에이전트 배치 · 화면)이 호출하게 하십시오.
.skills/ 아래에 폴더를 하나 만들고, 그 안의 .py 파일에 @zio_skill 함수를 적으면 끝입니다. 폴더 하나가 배포 단위 하나(가상환경 하나)입니다.
.skills/
└── <폴더명>/ ← 배포 단위 하나
├── <아무이름>.py ← @zio_skill 함수를 여기 적는다 (여러 개 가능)
├── requirements.txt ← (선택) 추가 라이브러리
├── main.py ← ⚡ 플랫폼 자동 생성. 직접 만들지 말 것
└── .venv/ ← ⚡ 플랫폼 자동 생성. 직접 만들지 말 것
requirements.txt 는 스킬을 띄울 때마다 지난번과 견주어, 바뀌었으면 깝니다. (pandas · fastapi · uvicorn · requests 는 적지 않아도 깔립니다.) 이미 떠 있는 스킬은 고쳐도 그대로입니다 — 그때 무엇을 해야 하는지는 아래 「라이브러리를 나중에 더했다면」 에 있습니다.
.skills/ 바로 밑에 놓은 낱개 .py 는 스킬이 아닙니다. 폴더가 있어야 플랫폼이 그 안에 main.py 와 가상환경(.venv)을 만들고, SDK 경로를 꽂아 프로세스를 띄웁니다.
폴더 없이 그냥 실행하면 ModuleNotFoundError: No module named 'zio_ontology' 가 납니다. 코드가 틀린 것이 아니라 띄워 주는 절차를 안 거친 것입니다. 폴더로 옮기면 그대로 돕니다.
SSH 컨테이너에는 파이썬이 깔려 있지 않습니다.python --version 도 import zio_ontology 도 여기서는 안 됩니다 — 없는 것이 정상이니 알아볼 필요가 없습니다. 여기는 코드를 적는 자리이고, 코드가 도는 곳은 스킬 러너 컨테이너입니다. 파이썬도, 가상환경도, zio_ontology 모듈도 전부 그쪽에 있습니다.
폴더로 두면 부르는 길이 셋 생깁니다. 셋 다 같은 함수를 부릅니다 — 어느 길로 부르든 결과가 같습니다.
주소는 하나뿐입니다. 포트로는 못 부릅니다
스킬은 스킬 러너라는 또 다른 컨테이너에서 돕니다. SSH 로 붙은 자리에서는 그 컨테이너가 아예 안 보입니다 — localhost 도, api:<포트> 도 안 열립니다. 포트 번호를 주소에 쓰지 마십시오. 어디에서 봤든 그것은 러너 안에서만 뜻이 있는 번호입니다.
어디서 부르나
주소
내 노트북 브라우저
플랫폼 주소 그대로 — https://<플랫폼 주소>/skills/<폴더명>/docs
SSH 안(터미널·IDE의 AI)
http://api:8002/api/artifacts/skills/call/<폴더명>/execute/<함수명>— 늘 이 주소입니다. 바깥 주소(https://…)로는 못 나갑니다.
부르는 길
언제 쓰나
/skills/<폴더명>/docs
브라우저로 열면 함수 목록이 나오고 눌러서 바로 실행됩니다(Swagger). 표 하나 만들기 같은 한 번짜리 작업은 이 길이 제일 빠릅니다. 좌측 스킬 탭에서도 열 수 있습니다.
POST /execute/<함수명>
curl 이나 다른 프로그램에서 부를 때. 인자는 JSON 본문의 최상위 열쇠로 찾아 넣습니다 — 함수의 인자 이름과 열쇠 이름이 같으면 됩니다. 브라우저 쪽에서는 앞에 /skills/<폴더명> 이 붙고, SSH 안에서는 앞에 http://api:8002/api/artifacts/skills/call/<폴더명> 이 붙습니다(아래).
skillFunction 노드
에이전트 빌더에서 폴더명/함수명 을 적어 워크플로우에 끼울 때. 배치와 디버거가 지나는 길이 이것입니다.
SSH 로 붙은 이 자리에는 **python·python3·pip 이 없습니다.**코드를 쓰는 곳과 도는 곳이 다릅니다 — 당신은 파일만 쓰고, 실행은 다른 컨테이너가 합니다. 그래서 아래가 python main.py 가 아니라 curl 한 줄입니다.
헷갈리기 쉬운 자리가 둘 있습니다. .venv/ 폴더가 보이지만 그 안의 python 은 다른 컨테이너를 가리키는 끊어진 링크이고, main.py 맨 아래의 if __name__ == "__main__": uvicorn.run(...) 도 여기서 부르라는 뜻이 아닙니다 — 러너가 그 파일을 그렇게 띄웁니다. apt install python3 같은 것을 시도하지 마십시오. 필요 없는 일이고 되지도 않습니다.
고친 뒤에 따로 할 일은 없습니다. 서버가 폴더 안 .py 의 수정 시각을 보고, 떠 있는 것보다 새로우면 알아서 다시 띄웁니다. 그냥 부르십시오.
(예전에는 손으로 restart 를 불러야 했고, 잊으면 옛 코드의 결과가 200 으로 돌아왔습니다 — 오류가 아니라 정상 응답이라 알아채기 어려웠습니다. 2026-09-24 에 그 판단을 서버로 옮겼습니다.)
다만 이것은 파이썬 코드(.py) 얘기입니다.index.html·CSS·JS 같은 정적 파일은 요청마다 디스크에서 새로 읽어 보내므로, 다시 띄울 필요 없이 브라우저 새로고침이면 바뀝니다. 화면(프론트)만 손봤다면 restart 를 부르지 마십시오 — 부를 함수의 파이썬을 고쳤을 때만 다시 띄웁니다.
restart 를 습관처럼 붙이지 마십시오. 그건 떠 있는 것을 죽이고 새로 띄웁니다 — 안 고쳤는데 부르면 프로세스만 갈려 느려집니다. 고쳤는지는 서버가 압니다.restart 는 프로세스가 꼬였을 때 쓰는 비상구입니다.
정적 파일은 원래 즉시 반영됩니다 — index.html·CSS·JS 는 요청마다 디스크에서 새로 읽습니다. 브라우저 새로고침이면 됩니다.
웹 화면에서 — 좌측 스킬 탭에서도 재시작할 수 있습니다(비상구).
브라우저로 /skills/<폴더명>/docs 를 여는 것도 같은 길을 지납니다 — 고쳤으면 그때도 알아서 새 코드로 뜹니다.
뜨다가 실패하면 그 폴더의 .skill_stderr.log 에 이유가 적힙니다. SSH 안에서는 이렇게 봅니다.
curl -s "http://api:8002/api/artifacts/skills/logs?skill_name=<폴더명>"
떴다고 내 함수가 등록된 것은 아닙니다. 문법 에러는 위처럼 재시작 자체가 실패하지만, @zio_skill 을 안 붙였거나 함수 이름에 오타가 있으면 프로세스는 멀쩡히 뜨고 부를 때서야 404 가 납니다. 그래서 재시작 응답에 지금 등록된 함수 목록(loaded_functions, 이름·시그니처·설명 첫 줄)을 함께 돌려줍니다 — 내가 부르려는 이름이 거기 있는지 먼저 보십시오. 하나도 없으면 warning 이 왜 비었는지 알려 줍니다. (_ 나 main 으로 시작하는 파일은 안 읽습니다.)
SSH 에서는 SDK 를 스킬 안에서만 부를 수 있습니다. 그래서 「KPI 등록해줘」 · 「회의록 고쳐줘」 같은 한 번짜리 일도 스킬 함수를 거칩니다. 함수가 쌓이는 자리이므로 아래 다섯을 지키십시오.
주제별 폴더에 모읍니다. KPI 일은 kpi_admin/, 온톨로지 설계 일은 ontology_admin/ 처럼 하는 일로 폴더를 나눕니다. 이미 그 주제의 폴더가 있으면 거기에 더합니다. 다른 일을 하는 스킬(예: 업무 데이터를 수집하는 스킬)에 끼워 넣지 마십시오 — 그 스킬을 고치거나 다시 띄울 때 엉뚱한 함수가 함께 흔들립니다.
대상과 값은 인자로만 받습니다 — 기본값에 박지 마십시오.def drop_kpi_result(kr_uuid: str = "dUsHzC5w") 처럼 uuid · 파일 경로 · 제목 · 결정 이유를 기본값으로 두면, 다음 사람이 인자 없이 불렀을 때 엉뚱한 것을 고치거나 지웁니다. 특히 지우기 · 고치기 함수는 대상 인자를 필수로 두고(def drop_kpi_result(kr_uuid: str)), 부를 때 -d '{"kr_uuid": "…"}' 로 넘깁니다.
한 가지 일에 함수 하나를 두고 다시 씁니다. 같은 일을 값만 바꿔 또 하면 새 함수를 짜지 말고 인자를 바꿔 부릅니다 (KPI 를 셋 등록하면 add_kpi_result 하나를 세 번).
SDK 의 기준은 이 매뉴얼(/agent_skills/.sdk_manual/)입니다. 스킬 폴더 안의 예전 메모 · 제안서 · 예제 코드는 그때의 SDK 를 적은 것이라 지금과 다를 수 있습니다 — 손잡이가 매뉴얼과 다르면 매뉴얼을 따르십시오. 예전 스킬이 지금 할 일을 다 하지 않을 수도 있습니다(예: 설계만 읽고 목표 · 버전은 안 읽는 분석 스킬).
담당자에게 줄 자료(설명 자료 · 보고서 등)는 작업 폴더(/agent_skills/) 안에 파일로 남기고 전체 경로를 알립니다. 플랫폼 밖 서비스에 올리지 마십시오 — 같은 인스턴스의 다른 사람이 볼 수 없고, 설계 내용이 플랫폼 밖으로 나갑니다.