Zio.Agent

When you describe the automation task you want to perform, AI designs it as an agent. Zio.agent.create() stores that design (nodes and connections) as a draft, which is then opened in the web Agent Builder for review, fine‑tuning, and activation. It’s not “build and run immediately”; instead, build → draft → review on the web → enable.

Overview

Method	Description
`Zio.agent.create(title, nodes, ...)`	Creates an agent draft from a concise spec (node list). Returns `{app_id, warnings}`.
`Zio.agent.update(app_id, nodes, ...)`	Replaces the entire design of an existing draft (fixes mistakes without deleting and recreating). `nodes` provides the entire design again. ⚠️ Activated agents are rejected — deactivate via the web first. If the graph changes, run `compile()` again.
`Zio.agent.list()`	List of my agents: `[{app_id, app_name, useYN, ...}]`.
`Zio.agent.get(app_id)`	Nodes/edges of a single agent.
`Zio.agent.compile(app_id)`	Compiles and validates the stored graph (draft remains — activation is via web).
`Zio.agent.debug(app_id, collection_id)`	Runs on a single real collection to test and view results (engine like a web debugger). Returns `{verdict, node_status, output, trace}`. `verdict` = did it run? (technical completion), `node_status` = was the task successful? (per-node success). ⚠️ Actual execution — if there are write nodes, data will be written.
`Zio.agent.delete(app_id)`	Deletes an agent.
`Zio.agent.skills(folder=, query=)`	List of available skill functions: `[{skill, params, returns, doc}]`. `params` = inputs (task arguments), `returns` = outputs (basis for binding `{{skill_node.field}}`), `doc` = author description. Check before building model nodes. If the list is long, narrow it with `folder=` (only that folder) or `query=` (case‑insensitive partial match on name, description, return fields, arguments).
`Zio.agent.twins()`	List of ontology design documents to reference — used when selecting a twin for an `ontology_link` node.

create — abbreviated spec

nodes only specifies what it does (by kind). The rest (start, end, coordinates, connections, model defaults) are filled in by the SDK.

from zio_ontology import Zio

got = Zio.agent.create(
    title="WBS 판정 에이전트",
    trigger="dynamic_worker",
    nodes=[
        # 1) 스킬 함수: 후보를 분석해 결과를 output 에 담는다
        {"kind": "skill", "name": "analyze_wbs",
         "skill": "agent_reinforce/analyze_wbs_candidates"},

        # 2) 모델 호출: 위 스킬 결과를 {{...}} 로 받아 판정한다
        {"kind": "model", "name": "model_call",
         "prompt": "주간업무일지 작업들을 WBS 항목에 붙이세요.\\n\\n"
                   "## 붙일 작업\\n{{analyze_wbs.pending_works}}\\n\\n"
                   "## 후보 항목\\n{{analyze_wbs.candidate_items}}",
         "output_schema": {"decisions": [
             {"work_name": "str", "item_name": "str", "is_new": "bool"}]}},
    ])

app_id = got["app_id"]
print(got["warnings"])   # 상태배선이 어긋나면 여기 담긴다

Node kinds (kind)

kind	What	Values Provided
`skill`	Calls a sandbox skill function. The result is stored in `output.<name>`.	`skill`=`"folder/function"`, `params` (optional)
`model`	Invokes an LLM (judgment, summary, etc.).	`prompt` (`{{노드.필드}}` binding), `output_schema`. Model inference flag and temperature default if not provided.
`ontology_link`	Connects the result to an ontology (graph).	`twin_id`, `node_id` (retrieved via `Zio.agent.twins()`)

Common: name is the name of this node and is used in {{name.필드}} binding. Subsequent if, tool, and loop can be added.

Most important – state wiring {{노드.필드}}
Section titled “Most important – state wiring {{노드.필드}}”

The model only looks at what is written in the prompt. To have the model use results from upstream nodes, you must explicitly include them in the prompt as {{상류노드.필드}}.

If omitted, it quietly returns an empty result without error (the model mistakenly thinks there is no data). create() will warn if the binding does not match upstream nodes — read carefully. Like in the example {{analyze_wbs.pending_works}}, a field returned by a skill node is referenced by its name.

Things the SDK fills automatically
Section titled “Things the SDK fills automatically”

Start and end nodes and connections (edges) – if edges are not provided, the SDK connects nodes in order.

Model inference flag and temperature – omitted in a model node are filled with default values (agent_llm_node).

Coordinates (x, y) – automatically positioned. Users can drag them in the web interface; moved positions are preserved.

output_schema can be given as a simplified form ({"decisions":[{"work_name":"str"}]}) or as a full JSON Schema.

Things not handled by the SDK – done in the web interface
Section titled “Things not handled by the SDK – done in the web interface”

Activation – create() only creates a draft. Actual execution (deployment) is enabled after review and testing in the web interface.

Custom Python code (model validation code, if conditions) – placed in the permission area; not included via SDK. Web-only.

Creating tools – handled separately (Zio.tool). Agents use existing tools.

Fine wiring and detailed settings are done in the web agent builder.

Order of Operations

# 1. 무엇을 쓸 수 있나 살펴본다 (모델 노드 짜기 전 필수)
for s in Zio.agent.skills():       # 스킬 함수 + 반환필드(returns)
    print(s["skill"], s["returns"])   # → {{스킬노드.필드}} 를 여기서 고른다
Zio.agent.skills(folder="agent_reinforce")   # 목록이 길면 폴더로
Zio.agent.skills(query="wbs")                # 또는 이름·설명·반환필드로 검색
for t in Zio.agent.twins():        # 이을 수 있는 온톨로지 설계서
    print(t)

# 2. 에이전트 초안을 만든다
got = Zio.agent.create(title="...", nodes=[...])

# 3. 목록/내용 확인
Zio.agent.list()
Zio.agent.get(got["app_id"])

# 4. (선택) 컴파일 검증 — 초안은 그대로, 문법/그래프만 확인
Zio.agent.compile(got["app_id"])

# 5. (선택) 샘플 1건으로 돌려 보고 결과·트레이스 확인
res = Zio.agent.debug(got["app_id"], 1628)   # 수집 레코드 id
print(res["verdict"])          # 돌았나 (기술적 완주)
print(res["node_status"])      # 업무가 됐나 (노드별 success) — SUCCESS라도 False가 있으면 그 노드는 업무 실패
print(res["output"])           # 노드별 결과

# 6. 어긋났으면 지우지 말고 고쳐 쓴다 (설계 전체를 다시 냄)
Zio.agent.update(got["app_id"], nodes=[...고친 설계...])
Zio.agent.compile(got["app_id"])   # 그래프가 바뀌었으니 다시 컴파일

# 7. 웹 에이전트빌더에서 열어 검토 → 활성화(켜기)

If the warnings from the result of create() are empty and the node appears correctly on the web, everything is fine. If something seems off, pass along exactly which node and which value is problematic to the responsible person.