LangGraph
Build stateful, multi-actor applications with LLMs.
— 공식 깃허브 리드미 최상단 문구. 이 문구만 보면 누구나 아이언맨의 자비스를 손쉽게 구현할 수 있을 것 같은 환상에 빠지게 된다.
분명 직관적인 그래프 구조랬는데, 정신 차려보니 코드에 State와 Node가 뒤엉킨 3,000줄짜리 현대미술이 완성되어 있다. 그냥 if-else로 하드코딩할 걸 왜 이걸 도입해서 사서 고생을 하고 있지?
1. 개요
LangChain Inc.에서 개발한 대규모 언어 모델(LLM) 기반의 에이전틱 워크플로우(Agentic Workflow) 구축용 프레임워크. 기존 랭체인의 고질적인 한계였던 '선형적인 흐름 제어의 한계'를 극복하고, 루프(Loop)와 순환 구조를 가진 복잡한 시스템을 구현하기 위해 탄생했다. 파이썬과 자바스크립트를 동시에 지원하지만, 인공지능 업계 룰에 따라 실무에서는 십중팔구 파이썬 버전이 다뤄진다.(...) 기본적으로 시스템을 상태 머신으로 모델링하여 제어하는 방식을 취하고 있다.
2. LCEL의 한계와 구원투수의 등장
과거 랭체인은 LCEL(LangChain Expression Language)이라는 자체 DSL을 밀어붙이며 모던 LLM 체이닝의 표준을 자처했다. 그러나 LCEL은 결정적으로 단방향 비순환 그래프(DAG) 형태에 최적화되어 있었기에, 에이전트가 도구를 사용한 뒤 다시 결과를 보고 판단을 수정하는 등의 반복적인 루프(Loop)를 설계하려면 코드가 기괴하게 꼬이거나 아예 구현이 불가능한 수준에 이르렀다. 결국 개발자들은 랭체인을 쓰면서도 핵심 루프는 하드코딩으로 따로 짜는 촌극을 벌였는데1, 이를 보다 못한 개발사에서 아예 '루프와 상태 관리가 중심이 되는 그래프 프레임워크'를 표방하며 들고나온 것이 바로 LangGraph다. 덕분에 드디어 제대로 된 다중 에이전트(Multi-Agent) 협업 아키텍처를 그럴듯하게 설계할 수 있는 길이 열렸다. 물론 설계만 쉽다.
3. 핵심 아키텍처: State, Node, Edge
LangGraph는 전체 워크플로우를 크게 세 가지의 기둥으로 나누어 관리한다.
- 상태 (State): 그래프 전체를 관통하는 유일한 진실의 원천(Single Source of Truth)이자 공유 메모리 영역이다. 각 노드가 실행될 때마다 이 상태를 읽고, 변경된 값을 덮어쓰거나 추가(Reducer 기능 활용)하면서 전체 흐름을 이어 나간다. 이 상태의 스키마를 꼼꼼하게 정의해두지 않으면 런타임에 원인 불명의 JSON 타입 에러를 직면하게 된다.(...)
- 노드 (Node): 실제 비즈니스 로직이나 LLM 호출, API 연동 등을 수행하는 실행 주체이다. 상태를 인풋으로 받아 연산을 수행한 뒤, 업데이트된 상태를 아웃풋으로 반환하는 함수 형태를 띤다.
- 엣지 (Edge): 노드와 노드 간의 이동 경로를 결정한다. 특히 LLM의 판단 결과에 따라 다음 행선지를 유동적으로 결정하는 조건부 엣지(Conditional Edge)가 핵심이며, 이것이 에이전트에게 '생각하고 행동하는' 자율성을 부여하는 마법의 소스다.
그리고 이 마법이 폭주하면 당신의 신용카드가 파괴된다.
4. 실무에서의 고통과 디버깅 잔혹사
개념은 아름답지만, 실제 프로덕션 레벨에서 사용하기 시작하면 온갖 런타임 기행에 멘탈이 바스러진다. 분기 조건이 조금만 어긋나도 에이전트가 출구를 찾지 못하고 자기 자신에게 계속 질문을 던지며 API 요금을 채굴하는 무한 대기 상태에 빠지기 일쑤며, 비동기(Async) 처리 환경에서 여러 에이전트가 동시에 상태를 업데이트하려다 병목이 생기거나 상태가 꼬여버리는 동시성 이슈도 빈번하게 터진다. 결국 이 디버깅 지옥을 탈출하기 위해 자사 유료 모니터링 툴인 LangSmith를 결제하게 만드는데, 이쯤 되면 랭체인 사의 고도의 가스라이팅이자 비즈니스 모델이 아닌가 합리적 의심이 들게 마련이다.2
5. 관련 밈 및 드립
5.1. 무한 루프와 카드 슬래시 (The Billing Loop of Doom)
조건부 에지(Conditional Edge) 설계 미스나 LLM의 환각(Hallucination) 현상으로 인해, 에이전트가 탈출 조건(Exit Condition)을 만족하지 못하고 계속해서 스스로 노드를 순환 호출하는 현상을 뜻한다. 퇴근 후 집에서 쉬고 있는데 슬랙으로 'OpenAI 사용량 경고' 알림이 울리는 순간의 공포는 겪어보지 않은 사람은 모른다. 개발자 커뮤니티에서는 '에이전트가 자아를 깨달은 줄 알았는데 그냥 내 월급을 채굴하고 있었다'며 자조하는 드립으로 애용된다.(...)
5.2. 결국은 거대한 if-else (State Machine Illusion)
세련된 '자율형 AI 에이전트 군단'을 만들겠다며 원대하게 LangGraph로 설계를 시작했지만, LLM의 비결정적 출력으로 발생하는 런타임 에러를 방어하다 보니 결국 모든 노드와 엣지 사이사이를 하드코딩된 정규표현식과 if-else 분기문으로 도배하게 되는 현상. 겉보기엔 화려한 AI 그래프 아키텍처지만 속을 까보면 고전적인 레거시 룰 베이스 엔진과 다를 바 없는 모습에 현타를 느끼는 개발자들의 넋두리에서 유래했다.
6. 여담
- LangSmith의 마약 같은 의존성: 디버깅이 워낙 헬게이트다 보니, 개발을 시작하면 자사 시각화/트레이싱 툴인 LangSmith를 켜놓지 않고서는 단 한 걸음도 앞으로 나아갈 수 없는 몸이 되어버린다. 거의 인앱 결제를 강요하는 부분 유료화 모바일 게임 수준의 사용자 경험을 자랑한다.
- 파이썬과 자바스크립트의 미묘한 격차: 랭체인 생태계가 늘 그렇듯, 문서화와 신규 기능 릴리즈는 파이썬 버전인
langgraph-py에 우선적으로 집중된다. JS/TS 진영인langgraphjs유저들은 공식 문서를 보며 파이썬 코드를 눈치껏 TypeScript로 번역해서 끼워 맞추는 번거로운 과정을 거쳐야 한다.(...) - 상태(State) 스키마의 뇌절: 에이전트 상태 구조를 설계할 때 타입 힌팅을 조금이라도 삐끗하면 파이썬 런타임이 무자비한 에러를 뿜어낸다. 특히 여러 노드가 동시에 특정 키 값을 업데이트하는 Reducer 패턴을 구현할 때 Operator 오용으로 데이터가 공중분해되는 현상이 자주 목격된다.