LangGraph에서 작업을 중단하고 사람에게 확인받기

실행 전에 판단을 돌려받기

에이전트가 자료를 읽고 초안을 만드는 동안에는 오류를 다시 고칠 수 있습니다. 하지만 외부 이메일 전송, 결제, 계정 삭제나 운영 데이터 변경은 실행 순간 실제 사람과 시스템에 영향을 줍니다. 모델의 확률적인 판단이나 모호한 사용자 문장을 곧바로 이런 부수 효과에 연결하면 잘못된 대상과 값이 확정될 수 있습니다. 위험한 행동 직전에 실행을 멈추고 책임 있는 판단을 돌려받아야 합니다.

Human-in-the-loop는 실행 중간에 대상, 인자와 예상 영향을 제시하고 사람의 결정을 받은 뒤 흐름을 이어가는 설계입니다. 사람은 그대로 승인하거나 값을 수정할 수 있고, 거부해 작업을 종료할 수도 있습니다. 이는 모든 모델 응답을 사람이 읽는 수동 운영이 아니라 위험도에 따라 자동화의 경계를 정하는 방식입니다.

그림: 체크포인트가 중단 시점의 상태를 보존하고 결정 후 재개를 돕습니다.

LangGraph의 interrupt는 호출 위치에서 실행을 멈추고 검토 화면에 필요한 값을 외부에 반환합니다. 그 직전까지의 그래프 상태는 체크포인터에 저장됩니다. 재개할 때는 같은 스레드 식별자와 체크포인터를 사용해 Command(resume=...)로 사람의 응답을 전달합니다. Command와 interrupt는 모두 langgraph.types에서 가져올 수 있습니다. 새 스레드로 호출하면 이전 실행의 연속이 아니라 별도 실행으로 취급될 수 있습니다.

from langgraph.types import Command, interrupt
 
def approve_email(state):
    decision = interrupt({
        "to": state["to"],
        "subject": state["subject"],
    })
    return {"approved": decision == "approve"}

이 함수만으로는 재개되지 않습니다. 그래프를 체크포인터와 함께 컴파일하고, 호출자가 스레드 식별자를 보존해야 합니다.

graph.invoke(Command(resume="approve"), config=config)

위 두 이름의 가져오기 경로와 재개 호출 형태를 보여 주기 위한 조각입니다. graph와 config는 체크포인터를 사용해 구성한 실행 객체와 동일한 스레드 설정이어야 합니다.

interrupt가 반환하는 값에는 검토에 꼭 필요한 정보만 넣습니다. 승인 화면은 수신자와 제목뿐 아니라 실제 보낼 본문, 첨부 여부와 사용될 계정을 보여 주는 편이 안전합니다. 반면 API 키나 내부 비밀값은 검토 데이터에 포함하지 않습니다. 사용자의 결정도 단순 문자열보다 approve, edit, reject처럼 허용된 형태로 검증합니다.

승인 화면에 필요한 정보

검토자는 대상, 변경 내용과 영향, 사용될 도구를 확인할 수 있어야 합니다. 단순한 “승인” 버튼만 보여 주면 잘못된 인자까지 함께 승인할 수 있습니다. 수정된 값은 다시 스키마와 권한 검사를 거치며, 원래 제안과 누가 언제 무엇을 바꿨는지도 감사 기록으로 남깁니다. 일정 시간 응답이 없을 때 자동 실행하지 말고 만료 또는 취소로 처리할지도 정해야 합니다.

중단 뒤 재개하면 interrupt가 들어 있는 노드가 처음부터 다시 실행될 수 있습니다. 따라서 중단 이전에 메일을 보내거나 결제를 승인하는 부수 효과를 두지 않습니다. 꼭 필요한 외부 호출은 별도 노드로 옮기고 결제나 메시지 전송에는 같은 요청이 두 번 처리되지 않도록 멱등성 키와 실행 기록을 사용합니다.

승인 대상은 위험과 불확실성을 기준으로 정합니다. 읽기 전용 검색은 자동 실행하고, 외부 공개나 금전 거래만 승인받는 식으로 단계화할 수 있습니다. 모든 작은 행동을 확인받으면 사용자가 내용을 제대로 읽지 않고 승인하는 피로가 생깁니다. 사람 승인은 위험을 없애는 장치가 아니라 자동 실행의 책임 경계를 명확히 하는 수단입니다.

상태 머신에 외부 도구를 연결할 때 연결 계층과 권한 경계를 구분하는 방법은 MCP의 호스트·클라이언트·서버 구분에서 살펴봅니다.

참고 문서

• LangGraph 공식 문서 — Interrupts
• LangGraph 공식 문서 — Persistence