LangGraph를 단순히 더 긴 체인으로 취급하지 마세요
LangGraph를 단계가 더 많은 LangChain으로 보지 마세요. 그런 실수는 망가진 에이전트를 만듭니다.
LangGraph는 상태(state), 분기(branches), 도구 호출(tool calls), 그리고 인간의 승인(human approval)이 필요한 워크플로우를 위한 것입니다. 또한 에러가 발생했을 때 재시작 없이 복구해야 하는 에이전트를 위한 것입니다.
LangGraph를 사용하려면 먼저 세 가지, 즉 상태(state), 중단(interrupts), 그리고 복구(recovery)를 정의해야 합니다.
첫 번째 경계: State Schema
단일 프롬프트의 경우 경계는 텍스트입니다. 하지만 LangGraph의 경우 경계는 State schema입니다. 다음 사항들을 결정해야 합니다:
- 어떤 필드가 노드 간에 이동하는가.
- 어떤 필드를 노드가 업데이트하는가.
- 병렬 분기에서 값이 어떻게 병합되는가.
- 어떤 값이 체크포인트(checkpoint)에 저장되는가.
- 어떤 값이 절대 유지되어서는 안 되는가.
여기서 Reducer는 매우 중요합니다. 메시지를 추가(append)하기 위한 적절한 규칙을 설정하지 않으면, 병렬 작업 중에 데이터가 누락될 수 있습니다.
작게 시작하세요. 하나의 schema, 하나의 node, 그리고 하나의 reducer로 그래프를 구축하세요. 이것조차 제대로 작동하지 않는다면, 도구(tools)를 추가하는 것은 단지 에러를 숨길 뿐입니다.
런타임 경계 (The Runtime Boundary)
compile()을 호출하기 전까지 그래프는 단순한 설명에 불과합니다. compile() 이후에는 런타임이 제어권을 갖습니다.
그래프가 실패할 때, 단순히 노드만 확인하지 마세요. 다음 네 가지를 점검하십시오:
- State schema가 해당 노드에 그 키를 쓸 수 있도록 허용하는가?
- 노드가 유효한 State 필드를 반환하는가?
- reducer가 데이터를 올바르게 병합하는가?
- conditional edge에 탈출 경로(exit path)가 있는가?
Human In The Loop
인간의 승인을 단순한 UI 기능으로 취급하지 마세요. 이를 그래프의 계약(contract)으로 취급해야 합니다.
신뢰할 수 있는 패턴은 다음과 같습니다:
- 모델이 도구 호출을 제안합니다.
- 그래프가 중단(interrupt)을 발생시킵니다.
- 인간이 작업을 승인하거나 수정합니다.
- 그래프가 정확히 그 지점부터 재개됩니다.
이를 통해 에이전트는 단순히 반응적인(reactive) 수준을 넘어 복구 가능한(recoverable) 존재가 됩니다.
스모크 체크리스트 (Your Smoke Checklist)
프로덕션에 배포하기 전에 다음 테스트를 실행하세요:
- 프로덕션 데이터가 없는 임시 디렉토리를 사용하세요.
- 최소한의 State를 정의하세요.
- 유효한 필드만 반환하는 노드를 하나 작성하세요.
- 추가(append) 작업을 위해 reducer를 사용하세요.
- 도구 작업 전에 중단(interrupt)을 하나 추가하세요.
- checkpointer를 추가하세요.
- 강제로 실패를 발생시킨 후 재개 동작을 확인하세요.
이 과정이 실패한다면, 도구를 더 추가하지 마세요. 문제는 런타임 경계에 있습니다.
LangGraph는 일회성 모델 호출을 위한 것이 아닙니다. AI가 검사 가능하고(inspectable), 일시 중지 가능하며(pausable), 검토 가능한(reviewable) 다단계 작업을 수행해야 할 때 사용하세요.
Optional learning community: https://t.me/GyaanSetuAi