멀티 에이전트

지도 위치 : 3일차 · README 4장의 ⑥ 서비스 층(사람의 승인) | 이전: 22차시 오케스트레이션 | 다음: 24차시 서비스 통합과 실행 키워드 : HITL, 인터럽트, 승인 게이트, 에스컬레이션

이 차시를 다 읽으면

1. HITL을 유와 종차로 정의하고, "사람이 손을 대는가" 축에서 자동 실행과 구별할 수 있다.
2. 흐름의 어디에 사람을 둘지 네 가지 기준(쓰기 · 되돌릴 수 없음 · 낮은 확신 · 민감정보)으로 고를 수 있다.
3. 승인 게이트를 LangGraph의 interrupt + 체크포인터 + Command(resume) 로 만드는 원리를 설명할 수 있다.
4. 승인 화면에 보여 줄 것과, 거절 · 수정 후 재개하는 흐름을 설계할 수 있다.
5. 에스컬레이션 기준을 정하고, 재개 때 쓰기 작업이 두 번 실행되지 않게 막을 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 "에이전트가 되돌릴 수 없는 일을 하기 전에, 어떻게 멈추고 사람에게 묻고 다시 이어 가나?" 입니다. 앞에서 배운 보안(8차시)에서 쓰기 도구는 사람의 확인이 필요하다고 했고, 18차시에서 체크포인터를 예고했습니다. 앞 차시(22차시)에서는 담당이 needs_approval을 돌려주면 "승인 대기"로 답만 했습니다. 이번에는 실제로 멈추고, 저장하고, 승인이 오면 재개 합니다. README 5.2 중심 축에서 보면, 모델이 흐름을 정하는 자리에 사람이 정하는 칸 을 끼워 넣는 일입니다.

---

1. HITL — 정의와 경계

1.1 정의

HITL (Human-in-the-Loop) — [에이전트 흐름 설계 방식]인데, [ 정해진 지점에서 실행을 멈추고 사람의 판단(승인 · 수정 · 거절)을 받아 그 결과로 흐름을 이어 간다 ]는 점에서 처음부터 끝까지 자동으로 도는 흐름과 구별된다.

1. 01초안실행할 내용 준비→
2. 02정지아직 실행하지 않음→
3. 03사람의 판단내용·영향 확인승인 → 실행 단계거절·수정 → 중지→
4. 04실행·기록승인 범위 안에서

1 / 4 · 초안재생

이 단계에서는

휴가 날짜·종류·대상 정리

단계를 누르면 해당 설명에서 멈춥니다.

일정 시간 기다렸다고 승인으로 간주하지 않습니다. 사람의 명시적 결정이 다음 단계를 정합니다.

1.2 반례 — 이건 HITL이 아닙니다

⭐ 첫 반례가 핵심입니다. "확인하고 신청해"는 부탁 이고, 그래프에 승인 노드를 두어 승인 없이는 신청 노드에 갈 수 없게 만드는 것이 강제 입니다(문장 2 — 모델은 판단하고, 코드는 지킨다).

💡 비유 (기억 보조용) — 결재 서류. 담당자가 기안을 올리면 결재자가 도장을 찍을 때까지 서류가 서랍에 보관 되고, 도장이 찍히면 그 서류 그대로 다음 단계로 갑니다. 서랍이 체크포인터입니다.

---

2. 어디에 사람을 두나

⚠️ 모든 곳에 사람을 두면 사람이 읽지 않고 승인 버튼만 누르게 됩니다. 승인 요청이 많을수록 승인의 무게가 가벼워집니다. 읽기 작업(휴가 잔여 조회, 규정 검색)에는 두지 않고, 위 네 기준에 걸리는 곳에만 둡니다.

---

3. 승인 게이트와 인터럽트

3.1 정의

승인 게이트 — [그래프 노드]인데, [ 사람의 승인 결과가 들어오기 전에는 다음 노드로 가지 못하게 막는다 ]는 점에서 State만 보고 바로 길을 고르는 라우터와 구별된다.

인터럽트 — [실행 제어 방식]인데, [ 그래프 실행을 노드 안에서 멈추고 State를 저장한 뒤, 외부 입력이 오면 그 자리에서 재개한다 ]는 점에서 오류로 실행을 끝내는 중단과 구별된다.

3.2 축 ⑦ — 멈춘 상태를 저장해야 재개할 수 있다

앞에서 배운 대로 LLM API는 무상태입니다(16차시). 그래프 실행도 프로세스 메모리에만 있으면, 승인을 기다리는 몇 시간 사이에 서버가 재시작되면 사라집니다. 그래서 인터럽트에는 체크포인터가 필수 입니다. 18차시에서 예고한 그 장치입니다.

from langgraph.types import interrupt, Command
from langgraph.checkpoint.memory import MemorySaver

def approval_gate(state: State) -> dict:
    decision = interrupt({                               # 여기서 멈추고 State 저장
        "작업": "장비 신청",
        "대상": state["requester_id"],
        "내용": state["draft"],                          # 예: 27인치 모니터 1대
        "되돌릴 수 있는가": "제출 후 취소는 IT팀 문의 필요",
    })
    if decision["action"] == "approve":
        return {"approved": True}
    if decision["action"] == "edit":
        return {"draft": decision["draft"], "approved": True}
    return {"approved": False, "reject_reason": decision.get("reason", "")}

app = g.compile(checkpointer=MemorySaver())              # 체크포인터 없으면 재개 불가
config = {"configurable": {"thread_id": "equip-req-0001"}}

app.invoke({"question": "모니터 하나 더 받고 싶어요", ...}, config)   # → 승인 대기에서 멈춤
# ... 몇 시간 뒤, 승인 화면에서 버튼을 누르면
app.invoke(Command(resume={"action": "approve"}), config)              # → 그 자리에서 재개

🔍 읽는 포인트

• interrupt({...}) — 그래프가 여기서 멈춥니다. 넘긴 dict가 승인 화면에 보여 줄 내용입니다(4절). 재개되면 resume에 넣은 값이 decision으로 돌아옵니다.
• checkpointer=MemorySaver() — 멈춘 State를 저장합니다. 단, MemorySaver는 메모리 에 저장하므로 서버가 꺼지면 사라집니다(축 ①의 메모리 쪽). 실습용이고, 운영에서는 SQLite · Postgres 같은 DB 기반 체크포인터 를 씁니다.
• thread_id — 어느 실행을 재개할지 가리키는 열쇠 입니다. 앞에서 배운 세션 ID(16차시)와 같은 역할이며, 다른 사용자의 thread_id로 재개되지 않도록 코드가 소유자를 확인합니다.
• Command(resume=...) — 같은 config(같은 thread_id)로 넘겨야 그 자리에서 이어집니다.
• 멈춘 상태와 대기 중인 인터럽트 내용은 app.get_state(config)나 실행 결과로 확인합니다. 반환 형식은 버전에 따라 다르니 공식 문서를 확인 하세요.

---

4. 승인 화면에 보여 줄 것

사람이 읽고 판단할 수 있는 화면이어야 승인이 의미를 가집니다(2절 경고).

⚠️ 누가 승인하나 도 코드가 정합니다. 본인 확인형(신청자가 최종 확인)인지, 결재형(팀장이 승인)인지 정하고, 승인 버튼을 누른 사람의 신원은 로그인 세션에서 가져와 권한을 검사합니다(8차시). 모델이 "팀장님이 승인하셨습니다"라고 쓴 글은 승인이 아닙니다.

---

5. 거절 · 수정 후 재개

💡 수정 후에 다시 승인을 받을지 는 정책입니다. 사람이 직접 고친 값이면 바로 실행하고, 수정 내용을 모델이 다시 해석해야 하면 한 번 더 승인 게이트를 거치게 합니다. 이것은 승인 노드 뒤에 조건부 엣지(19차시)로 그립니다.

---

6. 에스컬레이션

에스컬레이션 — [사람 개입 방식]인데, [ 봇이 처리하지 않고 사람 담당자에게 일 자체를 넘긴다 ]는 점에서 봇이 만든 초안에 사람이 도장만 찍는 승인 게이트와 구별된다.

넘길 때는 지금까지의 맥락을 요약해 담당자에게 함께 넘깁니다. 사용자가 같은 말을 처음부터 다시 하게 만들지 않는 것이 에스컬레이션의 품질입니다. 요약에는 17차시의 마스킹을 그대로 적용합니다.

---

7. ⚠️ 쓰기 도구의 멱등성 — 두 번 실행 막기

LangGraph에서 인터럽트로 멈췄던 노드는 재개될 때 그 노드의 처음부터 다시 실행 됩니다(세부 동작은 공식 문서 확인). 그래서 interrupt 앞에 쓰기 작업을 두면 재개 때 한 번 더 실행됩니다.

def submit(state: State) -> dict:
    if not state["approved"]:
        return {"answer": f"신청하지 않았습니다. 사유: {state['reject_reason']}"}
    ticket = request_equipment(
        requester_id=state["requester_id"],          # 로그인 세션 값
        item=state["draft"],
        idempotency_key=state["request_id"],         # 같은 키면 시스템이 한 번만 처리
    )
    return {"answer": f"신청했습니다. 접수번호 {ticket.id}"}

🔍 읽는 포인트

• if not state["approved"] — 거절 · 만료면 실행하지 않는 길 이 먼저입니다.
• idempotency_key=state["request_id"] — 신청 시스템이 이 키를 기억해 같은 키의 두 번째 요청을 무시합니다. request_id는 흐름이 시작될 때 한 번 만들어 State에 넣어 둡니다. 신청 시스템이 이런 키를 받지 못한다면, 우리 쪽 DB에 "처리한 요청 ID" 기록을 두고 확인합니다.

---

8. 오피스봇 장비 신청 승인 흐름

"모니터 하나 더 받고 싶어요"
      ↓
 [classify] → 장비신청 (19차시)
      ↓
 [it 에이전트] → 초안 작성, status="needs_approval" (21차시)
      ↓
 [approval_gate] ── interrupt ──→ (State를 DB에 저장, 대기)
      ↓                               ↓
      ↓                     승인 화면: 무엇을 · 누구 · 되돌릴 수 있나
      ↓                               ↓
      ↓ ←── Command(resume=...) ── 신청자 / 결재자 버튼
      ↓
   승인 · 수정 → [submit] (멱등성 키) → "접수번호 ..."
   거절       → [안내] → "신청하지 않았습니다. 사유: ..."
   만료       → [안내] → 알림

앞으로 다시 만납니다 — 24차시에서 이 흐름을 API로 엽니다. 대화 전송 엔드포인트가 승인 대기에서 멈추면 화면에 승인 요청을 띄우고, 승인 처리 엔드포인트 가 Command(resume=...)를 보내 재개합니다.

---

9. 실습 — 맡기고 검수하기

지시

오피스봇 장비 신청 흐름에 승인 게이트를 붙여줘.
참고 공식 문서: LangGraph의 human-in-the-loop(interrupt, Command), 체크포인터(persistence) 문서.
  설치된 langgraph 버전과, 재개 시 노드가 어디서부터 다시 실행되는지에 대한 문서 문장을 인용해 보고할 것.
구조: it 에이전트(초안) → approval_gate(interrupt) → submit 또는 안내 → END. 8절 그림대로.
제약:
- 체크포인터는 SQLite 기반(설치 버전 문서 기준)으로. MemorySaver는 쓰지 말 것.
- 쓰기(request_equipment)는 submit 노드에서만, 멱등성 키 필수. 테스트용 가짜 신청 시스템 사용.
- resume을 보낸 사람의 신원은 로그인 세션에서. thread_id 소유자가 아니면 거부.
테스트: ① 승인 ② 수정(모니터 → 노트북 거치대) 후 승인 ③ 거절 ④ 대기 중 서버 프로세스 재시작 후 승인
  ⑤ 같은 resume 두 번 ⑥ 다른 직원이 남의 thread_id로 승인 시도
보고 형식: [시나리오 | interrupt 내용 | resume 값 | 신청 시스템에 기록된 건수 | 최종 답] 표.
추측하지 말고 실행 출력 원문과 가짜 신청 시스템의 기록 원문을 붙여.

받을 증거

• 시나리오 6개의 표와 가짜 신청 시스템의 기록 원문 (건수 확인용)
• ④에서 재시작 전후의 프로세스 로그 와 재개 성공 기록
• 재개 동작에 대한 공식 문서 인용

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 23차시 노트만 근거로 비전공자용 5문제를 내줘.
"HITL이 아닌 것(부탁과 강제)", "어디에 사람을 두나", "인터럽트와 체크포인터(축 ⑦)", "재개 시 두 번 실행 막기"는 반드시 포함해줘.
내가 답한 뒤에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.