langchain-ai/langgraph-human-in-the-loop

langgraph-human-in-the-loop은(는) 무엇을 하나요?

이 스킬은 LangGraph에서 사람-루프 패턴, 승인 일시 중지 또는 오류 처리를 구현할 때 호출하세요. interrupt(), Command(resume=...), 승인/검증 워크플로 및 4계층 오류 처리 전략을 다룹니다.

개요

LangGraph의 사람-루프(Human-in-the-Loop) 패턴은 에이전트가 결정을 내리기 전에 사람의 승인을 받거나, 오류 발생 시 수동 개입을 허용합니다. 이는 중요한 워크플로우에서 안전성과 신뢰성을 보장합니다.

핵심 개념

interrupt()

• 목적: 에이전트 실행을 일시 중지하고 사람의 입력을 기다립니다.
• 사용법: interrupt()를 호출하면 현재 상태가 저장되고 실행이 중단됩니다.
• 재개: Command(resume=...)를 사용하여 중단된 지점부터 재개합니다.

Command(resume=...)

• 목적: 중단된 실행에 대한 응답을 제공합니다.
• 사용법: Command(resume={"approved": true})와 같이 재개 데이터를 전달합니다.
• 동작: 제공된 데이터는 interrupt() 호출 지점에서 반환됩니다.

승인 워크플로

1. 중단 지점 설정: 워크플로우에서 승인이 필요한 지점에 interrupt()를 삽입합니다.

   from langgraph.types import interrupt
   
   approval = interrupt("이 작업을 승인하시겠습니까?")
   

2. 재개 명령 보내기: 사용자 또는 외부 시스템이 Command(resume=...)를 보냅니다.

   from langgraph.types import Command
   
   command = Command(resume={"approved": True})
   

3. 결과 처리: 재개 데이터를 기반으로 워크플로우를 계속 진행합니다.

   if approval.get("approved"):
       # 승인된 작업 수행
       pass
   else:
       # 거부 처리
       pass
   

4계층 오류 처리 전략

LangGraph는 다음 계층으로 오류를 관리합니다:

계층 1: 재시도

• 설명: 일시적인 오류(네트워크 문제 등)에 대해 자동 재시도합니다.
• 설정: @tool 데코레이터에 retry 매개변수를 사용합니다.

계층 2: 폴백

• 설명: 재시도 실패 시 대체 동작을 정의합니다.
• 사용법: fallback 매개변수를 사용하여 대체 함수를 지정합니다.

계층 3: 오류 전파

• 설명: 처리할 수 없는 오류는 상위 핸들러로 전파됩니다.
• 동작: 에이전트 실행이 중단되고 interrupt()가 호출됩니다.

계층 4: 수동 개입

• 설명: 오류가 발생하면 사람이 직접 개입하여 문제를 해결합니다.
• 방법: Command(resume=...)를 사용하여 수정된 데이터를 제공합니다.

예제 코드

from langgraph.graph import StateGraph
from langgraph.types import interrupt, Command

class AgentState:
    data: dict
    approval: dict

# 승인 노드
def require_approval(state: AgentState):
    approval = interrupt("승인 필요: 데이터 검증")
    return {"approval": approval}

# 실행 노드
def execute_task(state: AgentState):
    if state.approval.get("approved"):
        # 작업 실행
        print("작업 실행됨")
    else:
        print("작업 거부됨")
    return {}

# 그래프 구성
builder = StateGraph(AgentState)
builder.add_node("require_approval", require_approval)
builder.add_node("execute_task", execute_task)
builder.add_edge("require_approval", "execute_task")
graph = builder.compile()

# 실행 및 재개
graph.invoke({"data": {}})
# 중단 후 재개 명령
graph.invoke(Command(resume={"approved": True}))

주의 사항

• interrupt()는 async 함수 내에서도 사용할 수 있습니다.
• 재개 데이터는 반드시 JSON 직렬화 가능해야 합니다.
• 오류 처리 전략은 프로젝트 요구사항에 맞게 조정하세요.
• 이 스킬은 Claude Code, Cursor, Codex 등 LangGraph를 지원하는 모든 플랫폼에서 동일하게 작동합니다.