Zio.Agent

하고 싶은 업무 자동화를 설명하면, AI 가 그것을 에이전트로 설계합니다. Zio.agent.create() 는 그 설계(노드·연결)를 초안으로 저장하고, 웹 에이전트빌더에서 열려 사람이 검토·정밀조정·활성화합니다. 짠 하고 만들고 바로 도는 게 아니라, 짠 하고 초안 → 웹에서 확인 → 켜기 입니다.

한눈에

Method	Description
Zio.agent.create(title, nodes, ...)	축약 스펙(노드 목록)으로 에이전트를 초안으로 만듭니다. {app_id, warnings} 를 돌려줍니다.
Zio.agent.update(app_id, nodes, ...)	기존 초안의 설계를 통째로 교체합니다(잘못 만든 것을 지우고 다시 만들 필요 없이 고쳐 씁니다). nodes 는 설계 전체를 다시 냅니다. ⚠️ 활성화된 에이전트는 거부 — 웹에서 비활성화 후. 그래프가 바뀌면 compile() 을 다시 하십시오.
Zio.agent.list()	내 에이전트 목록 [{app_id, app_name, useYN, ...}].
Zio.agent.get(app_id)	한 에이전트의 노드/엣지.
Zio.agent.compile(app_id)	저장된 그래프를 컴파일·검증합니다(초안 유지 — 활성화는 웹).
Zio.agent.debug(app_id, 수집id)	실제 수집 1건으로 돌려 보고 결과를 봅니다(웹 디버거와 같은 엔진). {verdict, node_status, output, trace}. verdict=돌았나(기술적 완주), node_status=업무가 됐나(노드별 success). ⚠️ 실제 실행 — 쓰기 노드가 있으면 진짜 씁니다.
Zio.agent.delete(app_id)	에이전트를 지웁니다.
Zio.agent.skills(folder=, query=)	쓸 수 있는 스킬 함수 목록 [{skill, params, returns, doc}]. params=입력(업무 인자), returns=출력({{스킬노드.필드}} 바인딩의 근거), doc=작성자 설명. 모델 노드 짜기 전 먼저 보십시오. 목록이 길면 folder=(그 폴더만)·query=(이름·설명·반환필드·인자 부분일치, 대소문자 무시)로 좁힙니다.
Zio.agent.twins()	참조할 온톨로지 설계서 목록 — ontology_link 노드에 쓸 twin 을 고를 때.

create — 축약 스펙

nodes 는 무엇을 하는가만 적습니다(kind 별). 나머지(start·end·좌표·연결·모델 기본값)는 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"])   # 상태배선이 어긋나면 여기 담긴다

노드 종류(kind)

kind	무엇	주는 값
skill	샌드박스 스킬 함수를 부릅니다. 결과가 output.<name> 에 담깁니다.	skill="폴더/함수", params(선택)
model	LLM 을 부릅니다(판정·요약 등).	prompt({{노드.필드}} 바인딩), output_schema. 모델·추론여부·온도는 안 주면 기본값.
ontology_link	결과를 온톨로지(그래프)에 잇습니다.	twin_id, node_id (Zio.agent.twins() 로 조회)

공통: name 은 이 노드의 이름이고 {{name.필드}} 바인딩에 쓰입니다. 후속으로 if·도구(tool)·loop 가 더해집니다.

가장 중요 — 상태배선 {{노드.필드}}

모델은 프롬프트에 적힌 것만 봅니다. 상류 노드의 결과를 모델이 쓰게 하려면 프롬프트에 {{상류노드.필드}} 로 명시해 넣어야 합니다.

안 넣으면 에러 없이 조용히 빈 결과가 납니다(모델이 “데이터가 없다”고 오판). create() 는 바인딩이 상류 노드와 안 맞으면 warnings 로 알려 줍니다 — 꼭 읽으십시오. 위 예시의 {{analyze_wbs.pending_works}} 처럼, skill 노드가 돌려준 필드를 이름으로 가리킵니다.

SDK 가 알아서 채우는 것

• start·end 노드와 연결(엣지) — edges 를 안 주면 nodes 순서대로 잇습니다.
• 모델·추론여부·온도 — model 노드에서 생략하면 기준값(agent_llm_node)으로 채웁니다.
• 좌표(x,y) — 자동 배치. 웹에서 사람이 끌어 옮깁니다(옮긴 자리는 그대로 둡니다).
• output_schema — 축약({"decisions":[{"work_name":"str"}]})으로 줘도 되고, 정식 JSON Schema 로 줘도 됩니다.

SDK 로 못 하는 것 — 웹에서 합니다

• 활성화 — create() 는 초안으로만 만듭니다. 실제 실행(배치)은 웹에서 검토·테스트 후 켭니다.
• 임의 파이썬 코드(모델의 검증코드, if 의 조건식) — 권한 자리에서 도므로 SDK 로는 넣지 않습니다. 웹 전용.
• 도구(tool) 만들기 — 별도(Zio.tool). 에이전트에서는 이미 있는 도구를 가져다 씁니다.
• 정밀 배선·미세 세팅 — 웹 에이전트빌더에서.

다룰 때 순서

# 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. 웹 에이전트빌더에서 열어 검토 → 활성화(켜기)

create() 결과의 warnings 가 비어 있고, 웹에서 노드가 제대로 보이면 잘 된 것입니다. 뭔가 어긋나면 어느 노드의 어느 값이 이상한지 담당자에게 그대로 전하십시오.