Zio.agent
웹 에이전트빌더에서 사람이 받는 것을 그대로 받습니다 — 우측 사이드바의 노드 목록 · 노드 속성 · 연결선 속성 · 도구. 그것을 보고 사람이 빌더에서 그리듯 그려 초안으로 저장하면, 사람이 빌더에서 열어 검수하고 사용으로 바꿉니다.
AI 는 사용안함(
useYN='N')인 에이전트만 만들고 고칩니다. 새로 만들면 사용안함으로 생기고, 사용 중인 에이전트는 고치기 · 컴파일 · 지우기가 거부됩니다. 사용으로 바꾸는 것은 사람이 빌더에서 검수한 뒤 합니다.
한눈에
섹션 제목: “한눈에”| Method | Description |
|---|---|
Zio.agent.nodes() |
빌더 우측 사이드바와 같은 것 {toolbox, definitions, edge, tools, options}. 노드마다 editor(칸 이름 · 설명 · 예시)와 node(끌어다 놓았을 때의 모양), 연결선은 edge.editor(「엣지 속성」 칸)와 edge.edge(이었을 때의 모양), 칸의 고를 값은 options. |
Zio.agent.get(app_id) |
한 에이전트의 nodes · edges — 빌더가 저장한 모양 그대로. |
Zio.agent.create(title, nodes, edges) |
새 에이전트를 사용안함으로 만듭니다. {app_id, app_name, useYN}. |
Zio.agent.update(app_id, nodes, edges) |
get() 으로 받은 것을 고쳐 돌려줍니다. 준 그래프가 저장됩니다. edges 를 안 주면 저장된 연결을 둡니다. |
Zio.agent.compile(app_id) |
빌더의 「컴파일」과 같은 검사 · 컴파일. 걸리면 빌더와 같은 문구로 돌려줍니다. |
Zio.agent.debug(app_id, 수집id) |
실제 수집 1건으로 돌려 보고 결과를 봅니다(빌더 디버거와 같은 엔진). {verdict, node_status, output, trace}. verdict=돌았나, node_status=업무가 됐나(노드별 success). ⚠️ 실제 실행 — 쓰기 노드가 있으면 진짜 씁니다. |
Zio.agent.list() |
에이전트 목록 [{app_id, app_name, useYN, ...}]. |
Zio.agent.delete(app_id) |
사용안함 에이전트를 지웁니다. |
Zio.agent.skills(folder=, query=) |
쓸 수 있는 스킬 함수 [{skill, params, returns, doc}]. returns 가 그 스킬이 돌려주는 필드라, 다른 노드에서 {{스킬노드이름.필드}} 로 씁니다. folder= · query= 로 좁힙니다. |
Zio.agent.twins() |
이을 수 있는 온톨로지 목록. |
Zio.agent.run(name, input) |
실행(저작 아님). 같은 인스턴스의 웹훅 · 사용 중(useYN='Y') 에이전트를 실행 접수합니다(빌더 디버거 · 웹훅과 같은 실행 엔진). name 은 그 에이전트의 app_name(웹훅 URL …/hooks/agent/<app_name> 의 마지막 조각 · Zio.agent.list() 의 app_name) — 화면 제목이 아닙니다. input 은 기존 형식 그대로 {"content": "…"} 또는 {"messages":[{"role":"user","content":"…"}]}. {run_id, status, return_mode} 를 바로 돌려줍니다 — 결과를 기다리며 붙잡지 않습니다. |
Zio.agent.result(run_id) |
run() 으로 접수한 실행의 지금 상태 · 결과. {status, answer, output, error}. status 가 success · error 면 끝난 것, queued · running 이면 아직입니다. 내가 run() 한 것이 아닌 run_id 는 없는 것과 같습니다(404). |
Zio.agent.nodes()로 쓸 노드 · 칸 · 연결선 칸 · 도구를 봅니다. 필요하면skills()·twins().- 고칠 때는
get()으로 지금 그래프를 받습니다. 새로 만들 때는 빈 그래프에서 시작합니다. - 노드는
definitions[종류].node에서 시작해id·position·editor의 칸을 채웁니다. 연결선은edge.edge에서 시작해 두 노드와 핸들을 정하고edge.editor의 칸을 채웁니다. create()또는update()로 저장하고,compile()로 검사합니다.- (선택)
debug()로 샘플 1건을 돌려 봅니다. - 사람이 빌더에서 열어 검수하고 사용으로 바꿉니다.
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)그린 것이 빌더에서 사람이 그린 것과 같아 보이면 잘 된 것입니다. 무엇이 어긋나는지는 빌더에서 그 노드 · 연결선을 눌러 우측 칸을 보면 사람과 AI 가 같은 것을 봅니다.
실행 — 이미 돌고 있는 에이전트를 부르고 결과 받기
섹션 제목: “실행 — 이미 돌고 있는 에이전트를 부르고 결과 받기”위까지는 저작입니다 — 초안(useYN='N')을 그리는 일. run() · result() 는 반대쪽, 실행입니다 — 사람이 검수해 **사용 중(useYN='Y')**으로 바꾼 웹훅 에이전트를 스킬에서 부르는 일. 웹훅으로 밖에서 부르는 것과 같은 실행 엔진을 지나므로, 새로 짜는 길이 아니라 이미 있는 길을 스킬에서 쓰는 것입니다.
run() 은 접수만 하고 바로 run_id 를 돌려줍니다 — 결과가 날 때까지 붙잡지 않습니다(그래야 화면이 멎지 않고, api 가 막히지 않습니다). 챗봇이라면 「요청 접수했어요, 결과 나오면 알려드릴게요」를 즉답으로 띄우고, result(run_id) 를 주기적으로 물어(폴링) status 가 success · error 가 되면 답을 뿌립니다. 에이전트 시작 노드의 「반환 방식」이 즉시 접수든 실행 후 반환이든, 스킬에서 읽는 법은 이 하나뿐입니다.
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} # 화면: 계속 기다림부를 때 넘기는
name은 그 에이전트의 app_name(웹훅 URL…/hooks/agent/<app_name>의 마지막 조각, 예:agent_2)입니다 — 화면 제목이 아닙니다. 모르면Zio.agent.list()로 확인합니다. 부를 수 있는 것은 같은 인스턴스의 웹훅 · 사용 중 에이전트뿐입니다. 다른 인스턴스 · 사용안함 · 웹훅이 아닌 에이전트는 부를 수 없습니다(없는 에이전트로 404).input은 빌더 디버거에 넣는 것과 같은 형식이라, 디버거에서 되던 입력이면 그대로 됩니다.
(주)지오유 · 경기 용인시 처인구 유림로154번길(유방동 673-2) 20-13
대표자 신달수·사업자등록번호 142-81-36612·통신판매업 신고번호 용인처인-0118호·개인정보 관리책임자 신달수·전자우편 shindalsoo@gmail.com·전화 1833-3623·팩스 02-6918-4006