③ 하네스 엔지니어링

🖐 실무 따라하기 — 복붙해서 따라 하면 됩니다

1. 1작업 폴더와 합성 민원 데이터 만들기

   터미널을 열고 작업 폴더를 만든 뒤, 처리할 민원 3건을 담은 inbox.json을 아래 내용 그대로 저장한다. 3번 민원은 일부러 개인정보(주민번호)를 노출시켜 '가드레일'이 걸리게 한 것이다. 실제 개인정보 대신 합성 데이터(주민번호 900101-1234567은 형식만 맞춘 가짜값)만 사용한다. 히어독(<<'JSON' ... JSON)은 파일만 만들 뿐 화면에 아무것도 출력하지 않으므로, 맨 끝에 붙인 cat inbox.json 이 저장된 내용을 화면에 다시 보여준다.

   터미널 명령

   ⧉ 복사

   mkdir -p ~/minwon-harness && cd ~/minwon-harness && cat > inbox.json <<'JSON'
   [
     {"id":"MW-2026-0001","name":"홍길동","phone":"010-0000-0000","text":"우리 동네 가로등이 3일째 꺼져 있어 밤에 위험합니다. 빠른 수리 부탁드립니다."},
     {"id":"MW-2026-0002","name":"김민원","phone":"010-0000-0000","text":"도로에 큰 포트홀이 생겨 차량이 파손됐습니다. 손해배상 관련 문의드립니다."},
     {"id":"MW-2026-0003","name":"박시민","phone":"010-0000-0000","text":"제 주민번호 900101-1234567 로 발급된 증명서에 오류가 있어 정정 요청합니다."}
   ]
   JSON
   cat inbox.json

   → 결과 히어독 저장 자체는 아무것도 출력하지 않지만, 맨 끝 cat inbox.json 때문에 방금 저장한 JSON 3건이 화면에 그대로 다시 출력된다. MW-2026-0003 안에 '900101-1234567' 문자열이 보이면 정상(뒤에서 이 값이 가드레일에 걸린다). 만약 아무것도 안 나오면 저장이 안 된 것이니 명령을 다시 확인한다.

2. 2도구(tool) 3개 정의 — 분류·개인정보검사·회신초안

   harness.py 파일을 만들고 아래 코드를 붙여넣는다. 이 블록은 하네스가 '호출해 쓸 도구' 3개다: classify(부서 분류), pii_scan(주민번호·전화 노출 검사=가드레일), draft_reply(회신 초안). pii_scan의 전화번호 패턴은 (?!0000) 부정형 전방탐색으로 합성 전화 '010-0000-0000'은 일부러 제외하고 실제 형식(예: 010-1234-5678)만 잡는다 → 실습에서 표준으로 쓰는 합성 전화가 오탐으로 걸리지 않는다. LLM 없이 규칙 기반으로 동작하므로 인터넷·키가 필요 없고 결과가 매번 같다(재현 가능).

   코드

   ⧉ 복사

   cat > harness.py <<'PY'
   import json, re, time
   
   # ---- 도구(tools): 하네스가 호출해 쓰는 단위 기능 ----
   DEPT_RULES = [
       (r"가로등|도로|포트홀|보수|수리", "도시안전과"),
       (r"손해배상|배상|보상", "법무담당관"),
       (r"증명서|발급|정정|주민", "민원여권과"),
   ]
   
   def classify(text):
       """민원 본문 -> 담당부서. 규칙을 위에서부터 검사해 '첫 매칭' 부서를 돌려준다. 안 걸리면 미분류."""
       for pattern, dept in DEPT_RULES:
           if re.search(pattern, text):
               return dept
       return "미분류"
   
   # 개인정보(가드레일) 패턴. 전화번호는 (?!0000)으로 합성 전화 010-0000-0000을 제외하고
   # 실제 형식(예: 010-1234-5678)만 잡는다 -> 실습용 합성 전화는 오탐되지 않는다.
   PII_PATTERNS = {
       "주민등록번호": r"\d{6}-\d{7}",
       "전화번호(실번호)": r"01[016789]-(?!0000)\d{3,4}-\d{4}",
   }
   
   def pii_scan(text):
       """개인정보 노출 검사(가드레일). 걸린 항목 이름 목록을 돌려준다."""
       hits = [name for name, pat in PII_PATTERNS.items() if re.search(pat, text)]
       return hits
   
   def draft_reply(mw_id, dept):
       return f"[{mw_id}] 접수되었습니다. 담당부서({dept})로 이관하여 처리 예정입니다."
   PY
   echo '도구 정의 저장 완료'

   → 결과 '도구 정의 저장 완료'가 출력된다. harness.py 파일이 생겼고 그 안에 classify/pii_scan/draft_reply 함수가 들어 있다. 아직 실행 로직은 없다(다음 step에서 추가). 정규식 주석에 '010-0000-0000을 제외'가 보이면 합성 전화가 오탐되지 않도록 처리된 것이다.

3. 3위험도 판정 + 재시도·타임아웃·폴백을 하네스에 추가

   이어서 아래 코드를 harness.py '끝에' 덧붙인다(>> 로 append). 여기서 위험도를 계산한다: 개인정보 노출 또는 손해배상 키워드가 있으면 HIGH(사람 승인 필요), 그 외 LOW(자동 처리). 또한 불안정한 외부 처리를 흉내 낸 run_step에 '타임아웃·재시도 3회·폴백'을 건다.

   코드

   ⧉ 복사

   cat >> harness.py <<'PY'
   
   # ---- 위험도 판정: 자동화 경계선 ----
   def assess_risk(text, pii_hits):
       if pii_hits:
           return "HIGH", "개인정보 노출"
       if re.search(r"손해배상|배상|보상", text):
           return "HIGH", "금전/법적 사안"
       return "LOW", "일반 처리"
   
   # ---- 재시도·타임아웃·폴백: 불안정 단계를 감싸는 래퍼 ----
   def run_step(fn, *args, retries=3, timeout=2.0):
       last_err = None
       for attempt in range(1, retries + 1):
           start = time.time()
           try:
               result = fn(*args)
               if time.time() - start > timeout:
                   raise TimeoutError("단계 응답이 타임아웃 초과")
               return result, attempt, None
           except Exception as e:
               last_err = str(e)
               time.sleep(0.1 * attempt)  # 지수적 대기(백오프)
       return None, retries, last_err  # 폴백: 실패로 확정
   PY
   echo '위험도/재시도 로직 추가 완료'

   → 결과 '위험도/재시도 로직 추가 완료' 출력. harness.py에 assess_risk와 run_step이 추가된다. run_step은 실패 시 최대 3번 재시도하고, 그래도 안 되면 (None, 3, 오류메시지)를 돌려주는 폴백 구조다. classify는 예외가 없으므로 정상 실행 시 tries=1로 돌아온다.

4. 4에이전트 루프 + HITL 승인 게이트 + trace 로그 완성

   마지막으로 아래 코드를 harness.py 끝에 덧붙인다. 이게 '처리절차 본체'다: inbox의 민원을 하나씩 돌며 도구를 순서대로 호출하고(실행 루프), 위험도가 HIGH면 자동 처리하지 않고 '승인 대기' 상태로 사람에게 넘긴다(HITL 게이트). classify가 실패하면 폴백으로 '미분류'를 채운다. 모든 판단은 trace 리스트에 기록되고, 루프는 최대 100건에서 강제 종료한다(루프 상한=폭주 방지).

   코드

   ⧉ 복사

   cat >> harness.py <<'PY'
   
   MAX_ITEMS = 100  # 루프 상한: 무한/폭주 방지
   
   def process(inbox):
       trace = []
       for i, mw in enumerate(inbox):
           if i >= MAX_ITEMS:
               trace.append({"event": "loop_cap_reached", "at": i}); break
           t = mw["text"]
           dept, tries, err = run_step(classify, t)
           if err: dept = "미분류"  # 폴백
           pii = pii_scan(t)
           risk, reason = assess_risk(t, pii)
           step = {"id": mw["id"], "dept": dept, "pii": pii,
                   "risk": risk, "reason": reason, "tries": tries}
           if risk == "HIGH":
               step["decision"] = "HITL_승인대기"      # 승인 게이트: 사람이 확인해야 진행
               step["reply"] = None
           else:
               step["decision"] = "자동처리"
               step["reply"] = draft_reply(mw["id"], dept)  # 자동 회신 초안
           trace.append(step)
       return trace
   
   if __name__ == "__main__":
       inbox = json.load(open("inbox.json", encoding="utf-8"))
       trace = process(inbox)
       print(json.dumps(trace, ensure_ascii=False, indent=2))
       auto = sum(1 for s in trace if s.get("decision") == "자동처리")
       hold = sum(1 for s in trace if s.get("decision") == "HITL_승인대기")
       print(f"
   요약: 자동처리 {auto}건 / 사람승인 대기 {hold}건 / 총 {len(trace)}건")
   PY
   python3 harness.py

   → 결과 3건의 trace가 JSON으로 출력된다(로컬 실행으로 확인한 실제 값). MW-0001은 dept='도시안전과', pii=[], risk='LOW', decision='자동처리'에 reply 초안이 채워진다. MW-0002는 '도로' 키워드가 DEPT_RULES에서 먼저 걸려 dept='도시안전과'로 분류되지만(손해배상 규칙보다 앞에 있음), '손해배상' 때문에 risk='HIGH', decision='HITL_승인대기', reply=null이 된다 — 분류 부서와 위험도 판정은 별개 단계임을 보여주는 지점이다. MW-0003은 본문의 주민번호 900101-1234567을 pii_scan이 잡아 pii=['주민등록번호'], dept='민원여권과', risk='HIGH', decision='HITL_승인대기', reply=null. 모든 건 tries=1. 맨 끝 요약 줄에 '자동처리 1건 / 사람승인 대기 2건 / 총 3건'이 정확히 나온다.

5. 5가드레일이 실제로 막는지 반례로 검증하기

   하네스가 '위험한 건을 자동으로 흘려보내지 않는지' 직접 확인한다. 아래 한 줄을 실행하면 개인정보가 든 MW-2026-0003이 자동처리(reply 채워짐)로 새어나갔는지 검사한다. 이것이 하네스의 '종료조건/안전 판정'이다.

   터미널 명령

   ⧉ 복사

   cd ~/minwon-harness && python3 -c "import json,harness; t=harness.process(json.load(open('inbox.json',encoding='utf-8'))); bad=[s for s in t if s['pii'] and s['reply']]; print('가드레일 통과: 개인정보 자동회신 0건' if not bad else '경고! 새어나간 건: '+str(bad))"

   → 결과 '가드레일 통과: 개인정보 자동회신 0건'이 출력된다(로컬 실행으로 확인). 즉 개인정보가 포함된 민원은 어떤 경우에도 자동 회신되지 않고 사람 승인으로 넘어간다는 것이 코드로 증명된다. 참고: pii_scan은 합성 전화 010-0000-0000은 (?!0000) 규칙으로 일부러 통과시키므로, 세 민원 모두에 든 이 합성 전화는 pii에 잡히지 않는다 — 걸리는 건 오직 MW-0003의 주민번호뿐이다. 만약 규칙을 잘못 고쳐 주민번호가 자동회신되면 '경고! 새어나간 건...'이 뜨므로, 이 검증이 회귀(regression) 방지선이 된다.