Zio.agent
In the Web Agent Builder, what a person receives is displayed exactly as it appears in the right sidebar: Node List · Node Properties · Edge Properties · Tools. By viewing this and drawing it like a person would in the builder, you can save it as a draft; then a human opens the draft in the builder to review and convert it into an active agent.
AI only creates and fixes agents that are not in use (
useYN='N'). When a new agent is created, it starts withuseYN='N'. Agents currently in use cannot be fixed, compiled, or deleted. Switching an agent to “in use” is done after a human reviews it in the builder.
Overview
Section titled “Overview”| Method | Description |
|---|---|
Zio.agent.nodes() |
Builder‑side sidebar‑like items {toolbox, definitions, edge, tools, options}. Each node has an editor (cell name · description · example) and a node (appearance when dragged), connection lines use edge.editor (the “Edge Properties” cell) and edge.edge (appearance when connected), and the cell’s selected value is stored in options. |
Zio.agent.get(app_id) |
The nodes · edges of a single agent – exactly as saved by the builder. |
Zio.agent.create(title, nodes, edges) |
Creates a new agent that is not yet used. Returns {app_id, app_name, useYN}. |
Zio.agent.update(app_id, nodes, edges) |
Takes what was returned from get() and updates it. The graph is saved. If edges is omitted, the stored connections are kept. |
Zio.agent.compile(app_id) |
Performs a check and compile similar to the builder’s “Compile”. If there are errors, returns the same messages as the builder. |
Zio.agent.debug(app_id, collectionId) |
Runs a single real collection item and shows the result (like the builder debugger engine). Returns {verdict, node_status, output, trace}. verdict = did it run?, node_status = did each task succeed? ⚠️ Actual execution – if there are write nodes they will actually write data. |
Zio.agent.list() |
List of agents [{app_id, app_name, useYN, ...}]. |
Zio.agent.delete(app_id) |
Deletes an unused agent. |
Zio.agent.skills(folder=, query=) |
Available skill functions [{skill, params, returns, doc}]. The returns field lists what the skill outputs; other nodes can reference them as {{SkillNodeName.field}}. Narrow results with folder= and query=. |
Zio.agent.twins() |
List of ontologies that can be linked. |
Zio.agent.run(name, input) |
Execute (not create). Submits a run request for an agent instance that is webhook‑enabled (useYN='Y') (the same engine as the builder debugger and webhook execution). The name is the agent’s app_name (the last part of the webhook URL …/hooks/agent/<app_name> – not the screen title). input follows the existing format: either {"content": "…"} or {"messages":[{"role":"user","content":"…"}]}. Immediately returns {run_id, status, return_mode} – it does not wait for the result. |
Zio.agent.result(run_id) |
Current state and result of a run submitted via run(). Returns {status, answer, output, error}. If status is success or error, the run has finished; if queued or running, it is still in progress. A run_id that was not created by run() behaves as if it does not exist (404). |
Sequence
Section titled “Sequence”- View the nodes, cells, connection line cells, and tools you will use with
Zio.agent.nodes(). If necessary, also viewskills()andtwins(). - When editing, retrieve the current graph with
get(). When creating a new one, start from an empty graph. - Nodes begin in
definitions[Type].nodeand fill in the fields forid,position, andeditor. Connection lines begin inedge.edge, set the two nodes and handles, and then fill in the fields ofedge.editor. - Save with
create()orupdate(), and validate withcompile(). - (Optional) Run a single sample with
debug(). - A person opens it in the builder to review and then switches it to production use.
import copyfrom zio_ontology import Zio
pal = Zio.agent.nodes()
g = Zio.agent.get(70) # 지금 그래프
# 노드 하나 — 빌더에 끌어다 놓듯 node 에서 시작해 칸을 채운다n = copy.deepcopy(pal["definitions"]["skillFunction"]["node"])n["id"] = "skill_log"n["position"] = {"x": 880, "y": 900}n["data"].update(node_name="log_result", label="실행 결과 기록", skillName="폴더/함수")g["nodes"].append(n)
# 연결선 하나 — 두 핸들을 잇듯 edge 에서 시작한다e = copy.deepcopy(pal["edge"]["edge"])e.update(id="e_exec_log", source="skill_exec", sourceHandle="bottom", target="skill_log", targetHandle="top")g["edges"].append(e)
# 도구 연결선 — 방향이 정해져 있다: 도구(source) → 모델호출(target), data.role="tool".# 거꾸로면 compile() 이 거절한다. 핸들은 모든 노드 공통 — 출력=right|bottom, 입력=left|top.te = copy.deepcopy(pal["edge"]["edge"])te.update(id="e_tool", source="skill_exec", sourceHandle="right", target="model_answer", targetHandle="left") # 출력(right) → 입력(left); model_answer=모델호출 노드te["data"] = {"role": "tool"}g["edges"].append(te)
Zio.agent.update(70, nodes=g["nodes"], edges=g["edges"])Zio.agent.compile(70)If what is drawn looks the same as what a person drew in the builder, then it has been done correctly. Any discrepancies can be seen by clicking on the node or connection line in the builder and looking at the right-hand pane; both the human and AI will see the same thing.
Execution — Calling an Already Running Agent and Receiving the Result
Section titled “Execution — Calling an Already Running Agent and Receiving the Result”Up to this point is creation—drafting (useYN='N'). run() and result() are the opposite side, execution—calling a webhook agent that has been approved for use (useYN='Y') from within a skill. Because it passes through the same execution engine as calling from outside via webhook, this is not a new path but reusing an existing one in the skill.
run() only accepts the request and immediately returns a run_id; it does not wait for the result (so the UI doesn’t freeze and the API isn’t blocked). In a chatbot you would respond with “Your request has been received; we’ll let you know when the result is ready,” and then periodically poll result(run_id). When the status becomes success or error, the answer is returned. Whether the agent’s start node uses an immediate return or returns after execution, this is the only way a skill reads it.
from zio_ontology import Zio, zio_skill
@zio_skilldef ask(content): """사용자 질문을 에이전트에 넘기고 접수증(run_id)만 돌려준다.""" # name 은 에이전트의 app_name (웹훅 URL 마지막 조각 · Zio.agent.list() 의 app_name). 화면 제목이 아니다. r = Zio.agent.run("agent_2", {"content": content}) # 화면: "요청 접수했어요. 결과 나오면 알려드릴게요" — 여기서 멈추지 않는다 return {"run_id": r["run_id"], "status": r["status"]} # status == "queued"
@zio_skilldef poll(run_id): """화면이 몇 초마다 부른다. 끝났으면 답을, 아직이면 '아직'을 돌려준다.""" res = Zio.agent.result(run_id) if res["status"] in ("success", "error"): return {"done": True, "answer": res.get("answer"), "error": res.get("error")} return {"done": False} # 화면: 계속 기다림The
namepassed when calling is that agent’s app_name (the last segment of the webhook URL…/hooks/agent/<app_name>, e.g.,agent_2). It is not the screen title. If unknown, check withZio.agent.list(). You can only call agents that are webhooks and in use within the same instance. Agents from other instances, unused agents, or non‑webhook agents cannot be called (they return 404). Theinputformat is the same as what you put into the builder debugger; if it works there, it will work here.
(주)지오유 · 경기 용인시 처인구 유림로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