솔직히 말하면, 처음 LangGraph를 접했을 때 “이게 왜 필요하지?”라는 생각이 먼저 들었다. LangChain만으로도 충분하지 않나. 프롬프트 엔지니어링 잘하면 그만 아닌가. 그런데 실제로 멀티에이전트 시스템을 프로덕션에 올려본 사람이라면 알 것이다. 에이전트가 두 개만 넘어가도 상태 관리가 지옥이 된다는 걸.
2024년부터 2025년에 걸쳐 AI 개발 생태계에서 가장 뜨거운 키워드 중 하나가 바로 LangGraph였다. GPT-5 시대를 앞두고 단순한 챗봇을 넘어, 실제 업무를 자율적으로 처리하는 AI 에이전트 시스템에 대한 수요가 폭발적으로 늘었기 때문이다. 그 중심에 LangGraph가 있다.
이 글은 LangGraph의 개념부터 아키텍처 설계, 멀티에이전트 패턴, RAG 연동, 스트리밍 처리, 실제 프로덕션 배포까지, 핵심을 한 곳에 정리한 종합 가이드다. LangGraph를 막 시작하는 사람이든, 이미 써봤지만 아키텍처 레벨에서 정리가 안 된 사람이든, 이 글 하나로 전체 그림이 잡히도록 썼다.
LangGraph가 뭔지, 왜 지금 이게 화제인가
LangGraph는 LangChain 팀이 만든 AI 에이전트 오케스트레이션 프레임워크다. 핵심 개념은 간단하다. AI 에이전트의 동작을 그래프(Graph) 형태로 정의한다. 노드(Node)에는 실행할 작업을 담고, 엣지(Edge)로 실행 흐름을 연결한다. 그리고 State라는 공유 메모리 구조로 노드 간 데이터를 주고받는다.
왜 이게 중요하냐면, 기존 LangChain의 체인 방식은 선형적이다. A → B → C 순서로 실행된다. 그런데 실제 업무는 그렇지 않다. 어떤 조건에서는 B를 건너뛰어야 하고, 어떤 상황에서는 A로 다시 돌아가야 한다. 루프가 필요하고, 분기가 필요하고, 병렬 처리가 필요하다. 그걸 가능하게 해주는 것이 LangGraph의 그래프 기반 설계다.
2025년 들어 LangGraph 1.0이 나오면서 Supervisor 패턴이 공식화됐다. 이전에는 개발자마다 멀티에이전트를 구현하는 방식이 제각각이었는데, 1.0부터는 표준화된 패턴이 생겼다. 이게 GPT-5와 맞물리면서 더 강력한 에이전트 시스템을 만들 수 있는 기반이 완성됐다고 보면 된다.
State: LangGraph의 심장, 상태 관리를 이해해야 한다
LangGraph를 처음 배울 때 가장 많이 막히는 부분이 State다. 상태관리라는 개념 자체가 백엔드나 프론트엔드 개발자에게는 익숙하지만, AI 에이전트 맥락에서는 조금 다르게 동작한다.
LangGraph에서 State는 전체 그래프를 흐르는 공유 데이터 컨테이너다. TypedDict나 Pydantic 모델로 정의하고, 각 노드는 이 State를 입력받아 수정된 State를 반환한다. 핵심은 State가 불변(immutable)처럼 동작한다는 점이다. 노드가 State를 “수정”하는 게 아니라, 변경된 부분만 담은 딕셔너리를 반환하면 LangGraph가 알아서 병합한다.
여기서 Reducer의 개념이 등장한다. 기본적으로 State 필드는 덮어쓰기(overwrite) 방식으로 병합되는데, 리스트처럼 누적되어야 하는 필드는 add_messages 같은 Reducer를 지정해줘야 한다. 이걸 이해하지 못하면 멀티턴 대화를 구현할 때 메시지가 계속 사라지는 황당한 버그를 만나게 된다.
글로벌 멀티턴과 에이전트별 멀티턴을 구분하는 것도 중요하다. 글로벌 State는 전체 그래프가 공유하는 대화 히스토리를 관리하고, 에이전트별 멀티턴은 특정 에이전트 내부에서만 반복되는 루프를 말한다. 복잡한 AI 시스템일수록 이 둘을 명확히 분리해서 설계해야 나중에 디버깅이 쉽다. 이 부분을 더 깊이 파고 싶다면 LangGraph 글로벌 멀티턴과 에이전트 멀티턴 대화 흐름 설계에서 설계 패턴별로 구체적인 코드와 함께 정리해뒀다.
워크플로우 vs 에이전트, 언제 무엇을 써야 하는가
LangGraph 공식 문서에서 자주 나오는 구분인데, 실제로 헷갈리는 사람이 많다. 워크플로우(Workflow)와 에이전트(Agent)는 비슷해 보이지만 설계 철학이 다르다.
워크플로우는 실행 흐름이 사전에 정의되어 있다. 개발자가 “이 조건에서는 A 노드로, 저 조건에서는 B 노드로”를 미리 코드로 지정한다. 예측 가능성이 높고 디버깅이 쉽다. 반면 에이전트는 LLM 자신이 다음에 무엇을 할지 결정한다. 도구(Tool)를 선택하고, 언제 작업을 끝낼지도 LLM이 판단한다. 자율성이 높지만 그만큼 예측하기 어렵다.
실무에서는 이 두 가지를 섞어 쓰는 경우가 대부분이다. 전체 파이프라인은 워크플로우로 정의하되, 특정 스텝에서는 에이전트에게 자율성을 준다. 예를 들어 고객 문의를 처리하는 시스템이라면, “문의를 분류 → 담당 에이전트에게 라우팅 → 에이전트가 도구를 자율적으로 사용해 답변 생성 → 답변을 검토 노드로 전달”처럼 설계한다. 분류와 라우팅은 결정론적 워크플로우로, 실제 답변 생성은 에이전트에게 위임하는 방식이다. 이 개념이 낯설다면 LangGraph 워크플로우와 에이전트 완벽 이해 가이드에서 초보자 눈높이로 잘 풀어두었으니 같이 보면 도움이 된다.
Tool Calling의 진화: OpenAI에서 LangGraph까지
AI 에이전트가 외부 세계와 상호작용하는 방법이 바로 Tool Calling이다. 이게 어떻게 발전해왔는지를 이해하면 LangGraph의 도구 연동 방식을 훨씬 잘 이해할 수 있다.
초기에는 Function Calling이라고 불렀다. OpenAI가 GPT에 JSON 스키마로 함수를 정의해서 LLM이 특정 형식으로 응답하게 만드는 방식을 도입했다. 문제는 이게 단발성이었다. 함수를 호출하고 결과를 받으면 끝이었다. 반복적인 도구 사용, 즉 도구 결과를 보고 다시 다른 도구를 호출하는 ReAct 패턴이 제대로 지원되지 않았다.
LangChain이 이 문제를 체인 방식으로 해결하려 했지만, 복잡한 멀티스텝 시나리오에서는 한계가 있었다. LangGraph는 이걸 그래프로 풀었다. 에이전트 노드 → 도구 실행 노드 → 다시 에이전트 노드로 이어지는 루프를 조건부 엣지로 표현한다. LLM이 “더 이상 도구가 필요 없다”고 판단할 때까지 이 루프가 반복된다.
실무에서 Tool Calling을 제대로 구현하려면 JSON 응답 신뢰성 문제를 반드시 다뤄야 한다. LLM이 항상 완벽한 JSON으로 응답하지는 않는다. 특히 오픈소스 모델을 쓸 때 이 문제가 심각해진다. LangGraph에서는 Output Parser와 Retry 로직을 노드 수준에서 처리할 수 있어서, 파싱 실패 시 자동으로 재시도하는 패턴을 깔끔하게 구현할 수 있다.
Supervisor 패턴: 멀티에이전트 시스템의 표준
LangGraph 1.0에서 가장 중요한 변화 중 하나가 Supervisor 패턴의 공식화다. 멀티에이전트 시스템을 만들 때 가장 직관적이면서도 강력한 패턴이다.
구조는 단순하다. Supervisor(감독자) 에이전트가 있고, 그 아래 여러 Worker(작업자) 에이전트가 있다. 사용자 요청이 들어오면 Supervisor가 판단해서 적절한 Worker에게 작업을 위임한다. Worker가 작업을 완료하면 결과를 Supervisor에게 돌려주고, Supervisor는 다음 단계를 결정한다.
실제로 구현해보면 Supervisor의 프롬프트 설계가 전체 시스템 성능의 70%를 좌우한다고 해도 과언이 아니다. Supervisor가 어떤 Worker에게 어떤 작업을 언제 위임할지를 명확하게 이해해야 하기 때문이다. 각 Worker의 역할과 능력을 Supervisor 프롬프트에서 구체적으로 정의하고, 모호한 요청에 대한 처리 방침도 명시해야 한다. GPT-5와 결합한 실제 Supervisor 설계 사례는 LangGraph 1.0 Supervisor 멀티에이전트 설계에서 코드 레벨로 다루고 있다.
GPT-5 시대를 맞이하면서 Supervisor 패턴의 활용 범위가 더 넓어졌다. 이전에는 LLM의 추론 능력 한계 때문에 복잡한 작업 분배가 어려웠는데, GPT-5급 모델들은 Supervisor 역할을 훨씬 정교하게 수행한다. 덕분에 수십 개의 전문화된 Worker를 조율하는 대규모 에이전트 시스템이 현실적으로 구현 가능해졌다.
서브그래프: 복잡성을 다루는 가장 우아한 방법
시스템이 복잡해질수록 하나의 거대한 그래프로 모든 걸 표현하려다 보면 관리가 불가능해진다. 이때 서브그래프(Subgraph)가 해법이 된다.
서브그래프는 독립적인 LangGraph 그래프를 다른 그래프의 노드처럼 사용하는 방식이다. 핵심은 각 서브그래프가 자신만의 State를 가질 수 있다는 점이다. 부모 그래프의 State와 서브그래프의 State가 완전히 독립적으로 존재하면서, 필요한 정보만 경계를 넘어 전달된다.
이게 왜 중요하냐면, 팀 단위 개발이 가능해지기 때문이다. 결제 처리를 담당하는 팀은 결제 서브그래프를 독립적으로 개발하고 테스트할 수 있다. 고객 지원 팀은 고객 상담 서브그래프를 따로 관리한다. 이걸 조립해서 전체 시스템을 만드는 방식이다. 마이크로서비스 아키텍처의 AI 에이전트 버전이라고 이해하면 쉽다.
서브그래프를 설계할 때 가장 신경 써야 할 부분은 State 경계 설계다. 어떤 정보가 부모에서 자식으로 흘러야 하고, 어떤 정보가 자식에서 부모로 올라와야 하는지를 명확히 정의해야 한다. 이 경계가 흐릿하면 서브그래프의 독립성이 무너지고, 결국 하나의 거대한 스파게티 그래프와 다를 바 없어진다.
RAG와 멀티에이전트: 문서 기반 AI 시스템의 새로운 지평
RAG(Retrieval-Augmented Generation)와 LangGraph의 결합은 단순한 기술 조합이 아니다. 이게 어우러지면 이전에는 불가능했던 수준의 지식 기반 에이전트 시스템이 만들어진다.
기존의 단순 RAG는 이렇게 동작한다. 질문이 들어오면 벡터 DB에서 관련 문서를 검색하고, 그걸 컨텍스트로 붙여서 LLM에게 넘긴다. 효과적이지만 한계가 명확하다. 한 번의 검색으로 답을 못 찾으면 그냥 모른다고 한다. 검색 결과가 충분하지 않아도 그걸로 답을 만들어낸다.
LangGraph 기반 멀티에이전트 RAG는 이걸 근본적으로 바꾼다. 검색 에이전트가 첫 검색 결과를 평가하고, 충분하지 않으면 쿼리를 개선해서 재검색한다. 다른 소스를 시도한다. 여러 문서의 정보를 종합해서 더 완전한 컨텍스트를 만든다. 이게 가능한 이유는 LangGraph의 조건부 루프 덕분이다. 이 패턴의 전체 구조와 구현 전략은 LangGraph 멀티에이전트 RAG: 문서 기반 질의응답의 새로운 패러다임에서 더 자세히 다루고 있다.
실제로 구현할 때는 langchain-postgres를 pgvector와 함께 쓰는 패턴이 프로덕션에서 안정적이다. 임베딩 저장, 유사도 검색, 메타데이터 필터링을 하나의 PostgreSQL 인스턴스에서 처리할 수 있어서 인프라 복잡도를 크게 낮출 수 있다.
Python Iterator, Generator, 그리고 Streaming
LangGraph를 실제 서비스에 적용하면 반드시 마주치는 문제가 스트리밍이다. 사용자는 LLM이 생성하는 텍스트를 실시간으로 보고 싶어한다. 처리 결과가 5초 후에 한꺼번에 뜨는 것보다, 글자가 하나씩 나타나는 게 훨씬 나은 경험이기 때문이다.
LangGraph의 스트리밍을 제대로 이해하려면 Python의 Iterator와 Generator부터 잡고 가야 한다. Generator 함수는 yield 키워드로 값을 하나씩 반환하는 함수다. 전체 결과를 만들어서 한 번에 반환하는 대신, 데이터가 준비될 때마다 즉시 내보낸다. LangGraph의 스트리밍이 정확히 이 원리로 동작한다.
LangGraph의 astream 메서드는 비동기 Generator를 반환한다. 그래프가 실행되면서 각 노드의 출력이 준비될 때마다 스트림을 통해 내보낸다. LLM의 토큰 스트리밍, 노드 실행 결과, 에이전트의 추론 과정까지 실시간으로 받을 수 있다. 스트리밍 모드별 차이와 실제 구현 코드는 Python Iterator, Generator 그리고 LangGraph & LangChain Streaming astream에서 확인할 수 있다.
스트리밍 모드에는 여러 종류가 있다. values 모드는 State 전체의 스냅샷을 스트리밍하고, updates 모드는 변경된 부분만 내보낸다. messages 모드는 LLM의 메시지 생성을 토큰 단위로 스트리밍한다. 실시간 채팅 인터페이스를 만들 때는 messages 모드를, 에이전트의 중간 처리 과정을 모니터링할 때는 updates 모드를 주로 쓴다.
Node.js 환경에서도 LangGraph 기반 에이전트 시스템을 구축하는 수요가 늘고 있다. Flowise는 LangChain과 LangGraph 워크플로우를 시각적으로 구성하고 Node.js 서버에서 실행할 수 있는 플랫폼으로, Python 스택이 없는 팀에게 진입 장벽을 크게 낮춰준다.
프로덕션 배포에서 마주치는 진짜 문제들
개발 환경에서 잘 돌아가던 에이전트가 프로덕션에서 문제를 일으키는 경우가 생각보다 많다. 주요 이슈를 미리 알고 있으면 삽질을 줄일 수 있다.
첫 번째는 체크포인팅(Checkpointing)이다. LangGraph는 그래프 실행 중 State를 체크포인트로 저장하는 기능을 제공한다. 이게 멀티턴 대화를 지속하는 핵심 메커니즘이다. 기본적으로는 메모리에 저장되는데, 프로덕션에서는 PostgreSQL이나 Redis 기반의 체크포인터를 써야 한다. 서버가 재시작되거나 인스턴스가 바뀌어도 대화 상태가 유지되어야 하기 때문이다.
두 번째는 동시성 처리다. 여러 사용자가 동시에 요청을 보낼 때, 각 사용자의 대화 State가 섞이지 않아야 한다. LangGraph에서는 thread_id로 대화 세션을 구분한다. 요청마다 고유한 thread_id를 부여하고, 체크포인터가 이 ID를 기준으로 State를 분리해서 관리한다.
세 번째는 LLM API 비용과 레이턴시 최적화다. 멀티에이전트 시스템은 하나의 사용자 요청에 LLM을 여러 번 호출할 수 있다. Supervisor가 한 번, 각 Worker 에이전트가 한 번씩. 거기다 도구 호출 루프까지 더해지면 LLM 호출 수가 급격히 늘어난다. 실제 프로덕션에서는 각 에이전트에 적합한 모델을 선택적으로 쓰는 전략이 중요하다. Supervisor처럼 복잡한 판단이 필요한 노드에는 강력한 모델을, 단순한 데이터 변환 노드에는 가벼운 모델을 쓰면 비용을 크게 절감할 수 있다.
Azure AI 환경에서 LangGraph를 운영할 때는 Azure OpenAI Service와의 연동 구성에 신경 써야 한다. 엔드포인트, API 버전, 배포 이름을 정확히 맞춰야 하고, 네트워크 정책에 따른 타임아웃 설정도 에이전트의 긴 실행 시간을 고려해서 여유 있게 잡아야 한다.
LangGraph 주요 문법, 반드시 알아야 할 핵심 패턴
이론은 충분하니, 실제로 자주 쓰는 패턴들을 정리해보자.
StateGraph는 가장 기본이 되는 그래프 클래스다. State 타입을 제네릭으로 받고, add_node로 노드를 등록하고, add_edge로 연결을 정의한다. compile()을 호출하면 실행 가능한 그래프 객체가 반환된다.
조건부 엣지(Conditional Edge)는 LangGraph의 핵심 기능이다. add_conditional_edges 메서드에 라우팅 함수를 전달하면, State를 보고 다음에 실행할 노드를 동적으로 결정할 수 있다. 에이전트가 더 이상 도구가 필요 없다고 판단하면 END 노드로, 도구가 필요하면 도구 실행 노드로 라우팅하는 패턴이 대표적이다.
Interrupt 기능도 실무에서 매우 유용하다. 그래프 실행 중 특정 시점에 인간의 승인을 받거나 추가 입력을 받아야 할 때 쓴다. interrupt_before나 interrupt_after로 특정 노드 실행 전후에 일시 정지를 걸 수 있고, 승인 후 invoke를 다시 호출해서 실행을 재개한다. Human-in-the-loop 패턴의 핵심 메커니즘이다.
마무리: LangGraph가 만들어가는 AI 에이전트의 미래
2025년을 기점으로 LangGraph는 단순한 실험적 프레임워크를 넘어 AI 에이전트 시스템의 사실상 표준(de facto standard)으로 자리를 잡아가고 있다. Supervisor 패턴의 공식화, 서브그래프를 통한 모듈식 설계, 체크포인팅으로 대화 상태 유지, astream을 통한 실시간 스트리밍까지, 프로덕션 AI 에이전트에 필요한 요소들이 하나의 프레임워크 안에 체계적으로 갖춰졌다.
이 글에서 다룬 내용을 다시 압축하면 이렇다. LangGraph는 State 관리와 그래프 기반 실행 흐름 제어를 통해 복잡한 AI 에이전트 시스템을 체계적으로 구현할 수 있게 해준다. Supervisor 패턴으로 멀티에이전트를 조율하고, 서브그래프로 복잡성을 분리하고, RAG와 결합해 지식 기반 에이전트를 만들고, 스트리밍으로 사용자 경험을 높이는 것이 LangGraph 시스템 설계의 핵심 흐름이다.
GPT-5 시대가 본격화되면서 LLM 자체의 능력은 빠르게 향상되고 있다. 하지만 그 능력을 실제 비즈니스 시스템에 녹여내는 오케스트레이션 레이어의 중요성은 오히려 더 커지고 있다. 모델이 아무리 강력해져도, 그 모델을 어떻게 조율하고 연결하느냐가 결국 시스템의 품질을 결정하기 때문이다. LangGraph는 바로 그 오케스트레이션을 담당하는 핵심 레이어다. 지금 LangGraph를 깊게 파고드는 것이 AI 에이전트 개발자로서 경쟁력을 갖추는 가장 현실적인 경로라고 생각한다.