A Bundle That Answers “How to Write and How to Run”
The documentation that lists what can be called (Zio.node, Zio.text, Zio.utils …) is in separate topic pages; here we cover where to place the function and how to execute it. Whatever you use, the placement and execution path are the same.
Write a Python script inside the platform’s .skills/ directory and attach the @zio_skill decorator; that function becomes both a skillFunction node and an AI tool. You don’t need to restart the entire platform—just reload that single skill (see “Reload” below).
You do not need to create main.py!
By writing only the @zio_skill function, the platform will automatically generate a main.py during cold start and also set up a virtual environment (.venv). Do not create either of those yourself.
You can create three versions with the same folder structure. What you build depends on who calls it.
Form
Caller
Placed in Folder
Function only
Agent node · other skill · curl
Only @zio_skill in *.py. The platform creates main.py.
Server renders the screen
Browser (HTML is generated by the server)
A custom main.py — a FastAPI route returns an HTMLResponse.
Browser renders the screen
Browser (index.html fetches data)
Custom main.py + index.html. See the Hosting documentation for details.
If you want to use your own main.py, delete the line at the top of that file that says @zio_skill decorator auto-register function. While that line is present, the platform rewrites main.py every time it launches the skill — any changes will be overwritten. After removing the line, do not touch it again.
main.py only does two things — registers the @zio_skill function and provides a route to serve the screen when needed.
Do not put code that starts doing work on its own— such as starting loops in a startup hook, launching threads, or calling something immediately at launch. A skill does work and returns an answer only when called. If there is periodic work to be done, make it a function and have the caller (agent deployment · screen) invoke it.
Create one folder under .skills/ and write the @zio_skill function in a .py file inside it; that’s all. One folder equals one deployment unit (one virtual environment).
.skills/
└── <폴더명>/ ← 배포 단위 하나
├── <아무이름>.py ← @zio_skill 함수를 여기 적는다 (여러 개 가능)
├── requirements.txt ← (선택) 추가 라이브러리
├── main.py ← ⚡ 플랫폼 자동 생성. 직접 만들지 말 것
└── .venv/ ← ⚡ 플랫폼 자동 생성. 직접 만들지 말 것
The requirements.txt should be updated whenever you launch a skill if anything has changed compared to the previous run. (pandas, fastapi, uvicorn, and requests are installed automatically even if not listed.) If a skill is already running, modifying it will keep it unchanged — what you need to do at that time is described in the section below titled 「라이브러리를 나중에 더했다면」.
After dragging the skillFunction node onto the canvas in Agent Builder, enter foldername/functionname format in the Skill Path field of the right property panel.
The skillFunction automatically injects the data required at runtime into the function’s parameters based on their names.
Reserved parameter name
Description and usage
input (dict)
The result returned by the previous node in the workflow canvas is automatically placed here. Example: user_name = input.get("username")
state (dict)
The entire workflow state dictionary managed by the LangGraph engine is provided as a whole. Useful for inspecting all context from prior flows.
Shared state variable
Variables that were returned by the previous skill node and merged into the output space. If a function’s parameter name matches a state key, the value is automatically injected at runtime.
additional_parameter (str)
The setting written in the additional_parameter input field of the Agent Builder property panel (text or JSON string) is injected unchanged.
A standalone .py placed directly under .skills/ is not a skill. The platform must have a folder so it can create main.py, a virtual environment (.venv), and inject the SDK path to launch the process.
Running without the folder results in ModuleNotFoundError: No module named 'zio_ontology'. The code isn’t wrong; you just didn’t go through the setup steps. Moving it into a folder fixes everything.
Python is not installed on the SSH container. Neither python --version nor import zio_ontology will work here — the absence is normal, so there’s no need to investigate. This is where you write code; the code runs in the skill runner container. Python, the virtual environment, and the zio_ontology module all exist on that side.
When you put it in a folder, three paths appear. All three call the same function — no matter which path you use, the result is identical.
There’s only one address. You can’t refer to it by port
The skill runs inside another container called the skill runner. From the SSH-attached environment, that container is completely invisible — localhost and api:<port> are not accessible. Do not include a port number in the address. Wherever you see it, the number only has meaning within the runner.
Where you call it
Address
In your laptop’s browser
The platform URL unchanged — https://<platform-address>/skills/<folder-name>/docs
Not in SSH (terminal/IDE AI)
http://api:8002/api/artifacts/skills/call/<folder-name>/execute/<function-name>— this is always the address. You cannot reach it from an external URL (https://…).
Calling Path
When to Use
/skills/<folder-name>/docs
Open in a browser to see the list of functions and click to execute directly (Swagger). For one‑off tasks like creating a table, this path is fastest. It can also be opened from the left Skills tab.
POST /execute/<function-name>
When calling via curl or another program. Arguments are placed as top‑level keys in the JSON body — the argument name and key name should match. In a browser, /skills/<folder-name> is prefixed; inside SSH, it’s prefixed with http://api:8002/api/artifacts/skills/call/<folder-name> (see below).
skillFunction node
When inserting folder-name/function-name into the workflow in Agent Builder. This is the path used by batch and debugger.
The SSH session you’re connected to does not have python, python3, or pip. The place where you write code is separate from the place where it runs. Therefore, what follows is a single curl command, not python main.py.
There are two confusing points. The .venv/ folder is visible, but its python is a broken link pointing to another container, and the if __name__ == "__main__": uvicorn.run(...) at the bottom of main.py does not mean you should run it here—the runner launches that file. Do not try commands like apt install python3; they are unnecessary and will not work.
The port is always 8002. Any address not present here cannot be called (403). Data is still read only via the SDK inside the skill.
POST /api/artifacts/skills/call/<폴더명>/execute/<함수명> 부르기
GET /api/artifacts/skills/logs?skill_name=<폴더명> 안 뜬 까닭
POST /api/artifacts/skills/restart 다시 띄우기 — requirements.txt 를 고쳤을 때 · 프로세스가 꼬였을 때
To leave a record of “who” in the audit, send -H "X-Zio-Who: $ZIO_WHO" along with your request. $ZIO_WHO is already populated when you log in. Since multiple people share a slot, omitting this line means no one knows who made the change.
Login, token, and cookie are not required.X-Zio-Who is for audit logging only. If you see “로그인이 필요합니다” (login required), your configuration is wrong; do not look for authentication—report that error to the operator.
The address is always the same. The only thing to remember is this single line, and you don’t need to worry about launching it—if it’s not running, it will start automatically when called. Creating a virtual environment the first time takes 1–2 minutes, after which responses are immediate.
Do not store the address in a shell variable. IDEs run commands one line at a time. Even if you capture the URL with URL=$(…) in one command, it won’t persist for the next command. Write the full address as shown below.
Replace <folder_name> and <function_name> with your own values. These two are distinct names—<folder_name> is the deployment unit, while <function_name> is the name you wrote in the def immediately under @zio_skill. If confused, look it up in the folder (see the third snippet below).
# 부른다. 안 떠 있으면 알아서 뜨고, 고쳤으면 알아서 새 코드로 다시 뜬다
curl -s -X POST http://api:8002/api/artifacts/skills/call/<폴더명>/execute/<함수명> \\
There’s nothing else to do after fixing. The server watches the modification time of .py files inside the folder and will automatically restart if they’re newer than what is running. Just call it.
(Previously you had to manually invoke restart, and if forgotten, the old code would return a 200 response—hard to distinguish from a normal success. That logic was moved to the server on 2026-09-24.)
This applies only to Python code (.py). Static files such as index.html, CSS, or JS are read fresh from disk on each request, so they update without needing a restart; just refresh the browser if you’ve changed the front end. Do not call restart unless you’ve modified the Python function that is being called.
Avoid habitually calling restart. It kills the running process and starts it anew—if nothing has changed, this will slow down the request because the process restarts unnecessarily. The server knows whether a change was made. Use restart only as an emergency when the process gets stuck.
Static files are reflected immediately — index.html, CSS, JS are read from disk on each request. A browser refresh suffices.
On the web interface — you can also restart from the left Skills tab (emergency).
Opening /skills/<folder_name>/docs in a browser follows the same path — if changed, it will automatically display the new code.
If startup fails, the reason is written to <folder_name>/.skill_stderr.log. From SSH you can view it with:
curl -s "http://api:8002/api/artifacts/skills/logs?skill_name=<folder_name>"
Starting does not mean your function is registered. A syntax error will cause the restart itself to fail, but if you omitted @zio_skill or made a typo in the function name, the process may start fine and only return a 404 when called. Therefore, the restart response includes the currently registered functions (loaded_functions, showing name, signature, first‑line description). First check whether your intended name is listed there. If none are present, a warning explains why it’s empty. Files starting with _ or main are not read.
In SSH, the SDK can be called only within a skill. Therefore even one‑off tasks such as “register KPI” or “edit meeting minutes” go through the skill function. Since it is a place where functions accumulate, observe the following five rules.
Collect them in topic folders.
For example, put KPI work in kpi_admin/, ontology design work in ontology_admin/. If a folder for that topic already exists, add to it. Do not insert it into a skill that performs other tasks (e.g., a skill that collects business data)—when you modify or restart that skill, unrelated functions may be affected.
Only receive target and value as arguments—do not hard‑code defaults.
If you write def drop_kpi_result(kr_uuid: str = "dUsHzC5w") with a default UUID, file path, title, or reason, the next person who calls it without arguments may unintentionally modify or delete something else. Especially for delete and edit functions, make the target argument required (def drop_kpi_result(kr_uuid: str)) and pass it as -d '{"kr_uuid": "…"}'.
One function per task, then reuse it.
Do not write a new function just because you want to change a value; call the same function with different arguments (e.g., register three KPIs by calling add_kpi_result three times).
The SDK standard is this manual (/agent_skills/.sdk_manual/).
Old notes, proposals, and example code in a skill folder were written for an earlier SDK version and may differ from the current one—if the interface differs from the manual, follow the manual. An older skill might not perform all tasks it is supposed to now (e.g., a design‑only analysis skill that does not read goals or versions).
Leave documentation (explanatory material, reports, etc.) as files in the work folder (/agent_skills/) and provide the full path.
Do not upload them outside the platform—other people on the same instance cannot see them, and design details would leak outside the platform.
requirements.txt is read when launching the skill. Unlike fixing a .py, fixing only this will not make it appear again, so launch it again with this single line. Remove what changed while launching.
curl -s -X POST http://api:8002/api/artifacts/skills/restart -H "Content-Type: application/json" -d '{"skill_name":"<폴더명>"}'
The installation output remains in the skill log (GET /api/artifacts/skills/logs?skill_name=<folder>) as [Agent.zio] requirements.txt 설치. If it failed, the reason is below that line.