콘텐츠로 이동

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).
  1. Zio.agent.nodes() 로 쓸 노드 · 칸 · 연결선 칸 · 도구를 봅니다. 필요하면 skills() · twins().
  2. 고칠 때는 get() 으로 지금 그래프를 받습니다. 새로 만들 때는 빈 그래프에서 시작합니다.
  3. 노드는 definitions[종류].node 에서 시작해 id · position · editor 의 칸을 채웁니다. 연결선은 edge.edge 에서 시작해 두 노드와 핸들을 정하고 edge.editor 의 칸을 채웁니다.
  4. create() 또는 update() 로 저장하고, compile() 로 검사합니다.
  5. (선택) debug() 로 샘플 1건을 돌려 봅니다.
  6. 사람이 빌더에서 열어 검수하고 사용으로 바꿉니다.
import copy
from 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_skill
def 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_skill
def 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