Zio.tools
Mail sending, reputation lookup, file download, and other tools registered on the screen are invoked within a skill. A skill cannot directly call /tools/ — that path is blocked from where the skill runs, and the only gateway to data is the SDK. Zio.tools passes through that gate on your behalf. It shows its ID and only allows tools that are whitelisted.
Do not swallow failures. If a tool fails, this function throws an exception — let it propagate so the skill ends in failure. Previously, when
/tools/was called directly and blocked, we swallowed the failure withtry/except, producing a “false success” that left the node marked as successful without storing results.
Which tool to call and with what arguments follows the specification of that tool — check the agent builder’s tool list. Within a skill you can use it via Zio.tools.list().
from zio_ontology import Zio
# 스킬에서 부를 수 있는 도구 목록for t in Zio.tools.list(): print(t["tool_id"], t["method"])
# 메일 발송 (인자는 그 도구의 규격을 따른다)Zio.tools.execute("send_email_via_smtp", { "to_email": "hong@example.com", "subject": "주간 업무 확인 요청", "body": "<p>확인 부탁드립니다.</p>", # 본문은 이미 완성된 것을 넘긴다})
# 도메인 평판 조회 — 결과(dict)를 그대로 돌려받는다whois = Zio.tools.execute("analyze_domain", {"domain_name": "example.com"})print(whois.get("is_registered"), whois.get("domain_age_days"))
# 파일 다운로드 — 바이너리는 bytes 로 온다pdf_bytes = Zio.tools.execute("gdrive_download_file", {"file_id": "1AbC..."})open("/tmp/spec.pdf", "wb").write(pdf_bytes)| Method | Description |
|---|---|
Zio.tools.list() |
List of tools callable from a skill. Returns [{tool_id, method}]. Tools not listed here cannot be called — raw tools such as shell, file, or raw query are not exposed to skills. |
Zio.tools.execute(tool_id, args) |
Invoke a single tool. tool_id is the name of the tool, and args is a dictionary of arguments that the tool accepts. On success it returns the result provided by the tool (usually a dict), or for binary outputs such as file downloads it returns bytes. |
Tools that cannot be called are blocked with guidance
Section titled “Tools that cannot be called are blocked with guidance”A
tool_idnot in the allowlist is denied with aPermissionError, and the message includes the list of callable tools. Shell execution, file read/write, and raw queries are not available to skills — if you need them, use the proper SDK interface. Do not call/tools/manually.
The role of a tool differs from that of a skill
Section titled “The role of a tool differs from that of a skill”
Zio.toolsis an entry point for invoking already registered tools. Reading and writing data is handled byZio.code,Zio.node,Zio.entity, andZio.ingestion— those are the official gateways through which a skill interacts with data.
Creating Tools — External REST API & Remote MCP Registration
Section titled “Creating Tools — External REST API & Remote MCP Registration”If you don’t have the required tool, create it yourself. You can register two types: an external REST API (like Postman where “you call this address in that way”), and a remote MCP server (such as DeepWiki·Context7, which is an MCP attached via URL). Once registered, the agent’s model will invoke them on its own (LLM tool calling) — REST uses arguments according to the params specification, MCP fills in action and arguments.
v1 creates
restapiandremote HTTP MCP. The local stdio MCP·skill is a boundary that launches a process; it’s still only for the web admin, andcustom_scriptis unimplemented.A created tool starts as a draft (
useYN='N') — you review it in the web ToolBuilder preview and enable it. Tools are shared across the entire instance, so this review gate is important.Security: The actual calls to tools you create originate from an isolated location (skillnet) — therefore they reach external addresses but cannot access internal services (neo4j·redis, etc.). Even if you put an internal address in
url, it won’t work (that’s how it’s designed).
from zio_ontology import Zio
# 바깥 REST API 를 도구로 등록 (초안으로 생성)got = Zio.tools.create( title="날씨 조회", url="https://api.weather.com/v1/current?city={{city}}", method="GET", headers={"X-API-Key": "..."}, params=[ {"key": "city", "type": "string", "required": True, "description": "조회할 도시명"}, ])print(got["id"], got["tool_id"]) # -> 53 weather_...print(got["warnings"]) # 이상하면 여기 담긴다 — 꼭 읽는다
# 한 도구의 전체 설정 보기 (id 또는 tool_id 로)Zio.tools.get(got["tool_id"])
# 고치기 (안 준 것은 유지, tool_id 는 안 바뀐다)Zio.tools.update(got["id"], description="도시별 현재 날씨")
# ── 원격 MCP 서버 등록 (DeepWiki·Context7 처럼 URL 로 붙는 MCP) ──mcp = Zio.tools.create( title="내 위키", type="mcp", url="https://mcp.deepwiki.com/mcp", # 원격 HTTP MCP 서버 주소 transport="http") # "http"(Streamable) 또는 "sse"# 모델은 실행 시 action_name(예: ask_question) + JSON 인자로 호출합니다.# 로컬 실행(command 방식) MCP 는 SDK 로 못 만듭니다 — 원격 HTTP MCP 만.
# 지우기 (사용자가 만든 것만 — 시스템 도구는 거부)Zio.tools.delete(got["id"])
# 이제 웹 도구 빌더에서 열어 프리뷰 → 활성화(켜기)| Method | Description |
|---|---|
Zio.tools.create(title, url, ...) |
Registers a tool (draft). restapi (default): method·headers·auth· params·body·response_schema, where params is the LLM input contract ({key,type,required,description,default}), and {{var}} automatically becomes an argument. mcp (type="mcp"): url·transport (http/sse) — only remote HTTP MCP (local stdio is web‑admin only). Returns {id, tool_id, warnings}. |
Zio.tools.get(ref) |
Retrieves the full configuration of a single tool (input params, authentication, body, etc.). ref can be an id or tool_id. |
Zio.tools.update(ref, ...) |
Replaces settings for an existing user tool. Unspecified fields are preserved; tool_id (name) is immutable. System tools are rejected. |
Zio.tools.delete(ref) |
Deletes a user tool (system tools are rejected). |
System Tools vs My Tools
Section titled “System Tools vs My Tools”The system tools that are provided by default to all users cannot be created or modified via the SDK (they can only be read and called). Creating something with
createmakes it an own (user) tool, andupdate·deleteapply only to your own tools. View the list withZio.tools.list().
(주)지오유 · 경기 용인시 처인구 유림로154번길(유방동 673-2) 20-13
CEO 신달수·Business no. 142-81-36612·E-commerce no. 용인처인-0118호·Privacy officer 신달수·Email shindalsoo@gmail.com·Tel 1833-3623·Fax 02-6918-4006