LangGraph란? AI 에이전트의 작업 흐름을 관리하는 프레임워크 사용법

개발 테크

16시간 전

조회수

AI Agent 업무 루프 설계 AI 에이전트가 처리하는 업무가 복잡해지면서, 모델에 프롬프트를 입력하고 결과를 받는 방식만으로는 안정적인 자동화를 만들기 어려워졌습니다.

여러 단계가 연결된 AI 에이전트에서는 AI가 무엇을 할 수 있는가보다 어떤 순서와 조건으로 움직일지가 중요해집니다. 이를 위해 AI 에이전트의 작업 흐름을 Graph로 먼저 설계한 뒤 실행하는 LangGraph가 등장했습니다.

이번 글에서는 LangGraph가 어떤 프레임워크이고 어떻게 작동하는지, 사용법과 주의사항까지 정리하겠습니다.

LangGraph 핵심 요약

LangGraph는 AI 에이전트의 작업 흐름을 그래프로 설계하는 프레임워크입니다. 각 작업을 연결하고 조건에 따라 다음 작업을 결정할 수 있어 복잡한 AI 워크플로를 체계적으로 구성할 수 있습니다.
작업 상태를 저장해 중단된 에이전트 작업을 이어갈 수 있습니다. 장시간 실행되는 작업이 실패하거나 사람의 승인을 기다려야 할 때 진행 상태를 보존하고 이후 다시 이어서 실행할 수 있습니다.
AI의 판단과 사람이 개입해야 하는 영역을 함께 설계할 수 있습니다. 중요한 작업 앞에서 에이전트를 멈추고 사람이 결과를 확인·수정·승인한 뒤 다음 단계로 진행하는 구조를 만들 수 있습니다.
장기적이고 복잡한 AI 에이전트 구축에 적합합니다. 멀티 에이전트, 반복 작업, 조건 분기, 오류 복구, 메모리가 필요한 업무 자동화에서 활용 가치가 큽니다.

LangGraph란?

LangGraph가 ai 에이전트 워크플로우를 설계하는 모습의 이미지입니다. LangGraph는 AI 에이전트가 수행하는 여러 작업과 판단 과정을 그래프 형태로 설계하는 오픈소스 프레임워크입니다.

여러 단계가 연결된 AI 에이전트 작업에서 AI가 어떤 순서와 조건으로 움직일지를 그래프 형태로 구성하고, 각 단계의 상태와 이동 조건을 관리합니다. 이를 통해 자동화 업무에서 AI가 진행할 일과 사람이 판단해야 하는 일을 구분합니다.

덕분에 사용자는 AI 에이전트 워크플로우의 흐름을 미리 통제하면서 필요한 지점에서만 AI의 판단을 호출하는 휴먼 인 더 루프(Human-in-the-loop) 시스템을 설계할 수 있습니다.

LangGraph가 주목받는 이유

langgraph 공식 GitHub 저장소의 이미지입니다.

* 이미지 출처: langgraph 공식 GitHub 저장소

1. AI 에이전트의 작업 흐름을 명확하게 설계할 수 있습니다

일반적인 AI 에이전트는 사용자의 요청을 받으면 모델이 다음 행동을 판단하고, 도구를 실행한 뒤 그 결과를 다시 모델에 전달하는 반복 구조로 작동합니다.

반면 LangGraph는 이 흐름을 State, Node, Edge 세 가지 요소로 구성합니다.

State는 현재 작업에서 유지해야 하는 정보를 담습니다.
Node는 검색, 분석, 도구 호출, 에이전트 실행처럼 실제 작업이 일어나는 지점입니다.
Edge는 한 작업이 끝난 뒤 어디로 이동할지 결정합니다.

AI가 작업할 부분과 사람이 판단해야 할 부분을 명확하게 구분할 수 있어, 규모가 큰 자동화 과정에서도 예측 가능한 워크플로우를 설계할 수 있습니다.

2. 중단된 작업을 처음부터 다시 시작하지 않아도 됩니다

LangGraph는 장시간 작업에서도 작업 흐름을 제어할 수 있도록 durable execution 방식을 사용합니다. 각 Node 실행이 끝날 때마다 그 시점의 State를 checkpoint로 저장해, 중단된 지점부터 작업을 이어갈 수 있습니다.

덕분에 중간에 서버가 재시작되거나 API 오류가 발생해도 처음부터 다시 실행할 필요가 없습니다. 이미 끝난 단계를 반복하지 않으므로 불필요한 토큰 소비와 작업 지연을 줄일 수 있습니다. 오래 실행되는 업무의 자동화 시스템을 안정적으로 운영해야 할 때 유용합니다.

3. 여러 AI 에이전트의 역할을 하나의 흐름으로 연결할 수 있습니다

자동화 단계에서 AI 에이전트의 워크플로우는 하나로 끝나지 않습니다. 여러 워크플로우가 이어지면서 더 큰 자동화 시스템을 이룹니다.

LangGraph는 이렇게 확장된 워크플로우에서 오케스트레이션 계층으로 활용할 수 있습니다. 완성된 워크플로우를 상위 그래프의 Node로 사용해, 개별 워크플로우는 독립된 단위로 유지합니다. 그 사이의 실행 순서와 조건만 상위 그래프에서 정의합니다.

덕분에 업무 단위로 나눠 만든 자동화를 하나로 묶어, 조직 전체 규모의 AI 에이전트 워크플로우로 확장, 관리할 수 있습니다.

LangGraph의 사용법

실행 환경 준비

LangGraph는 Python 3.10 이상에서 동작합니다. LangGraph는 Python 3.10 이상에서 동작합니다. 먼저 설치된 버전을 확인하고, 프로젝트별로 패키지를 분리할 수 있도록 가상환경을 만듭니다.

LangGraph를 위해 Python에서 가상환경을 실행했습니다. 가상환경이 활성화되면 위 이미지처럼 명령줄 앞에 (.venv) 표시가 나타납니다.

pip install -U langgraph langchain-openai

가상환경에서 명령어를 입력해 LangGraph와 모델 연동 패키지를 함께 설치한 화면입니다. 가상환경에서 명령어를 입력해 LangGraph와 모델 연동 패키지를 함께 설치합니다.

State 정의

그래프 전체가 공유할 데이터 구조를 먼저 정합니다. 여기서 정의한 필드가 모든 Node의 입출력이 되므로 가장 먼저 작성합니다.

python

from typing import TypedDict

class State(TypedDict):

topic: str

draft: str

review: str

retry: int

Node 작성

State를 받아 갱신할 필드만 딕셔너리로 반환하는 함수입니다. 전체 State를 반환할 필요가 없습니다.

python

def write(state: State):

count = state["retry"] + 1

return {"draft": f"{state['topic']} 초안 v{count}", "retry": count}

def review(state: State):

result = "pass" if state["retry"] >= 2 else "fail"

return {"review": result}

def finalize(state: State):

print("최종 결과:", state["draft"])

return {}

조건 분기 정의

State 값을 보고 다음 Node 이름을 문자열로 반환하는 함수입니다. AI 판단과 규칙의 경계가 여기서 정해집니다.

python

def route(state: State):

if state["retry"] >= 3:

return "finalize"

if state["review"] == "fail":

return "write"

return "finalize"

retry >= 3 조건이 무한 루프를 막는 안전장치입니다.

Graph 조립

Node를 등록하고 Edge로 잇습니다. 조건 분기는 add_conditional_edges로 연결합니다.

python

from langgraph.graph import StateGraph, START, END

builder = StateGraph(State)

builder.add_node("write", write)

builder.add_node("review", review)

builder.add_node("finalize", finalize)

builder.add_edge(START, "write")

builder.add_edge("write", "review")

builder.add_conditional_edges("review", route)

builder.add_edge("finalize", END)

review에서 write로 되돌아가는 경로가 순환입니다. 체인 구조로는 만들 수 없는 부분입니다.

컴파일과 실행

compile()로 그래프를 확정한 뒤 invoke()로 실행합니다.

python

graph.invoke({

"topic": "LangGraph",

"draft": "",

"review": "",

"retry": 0,

})

실행 결과

터미널에서 python test_graph.py를 실행하면 write에서 review로 이동한 뒤 다시 write로 되돌아가는 순환 구조가 출력됩니다.

LangGraph 사용 시 주의사항

1. 단순한 AI 작업에는 오히려 구조가 복잡해질 수 있습니다

LangGraph는 모든 AI 애플리케이션에 필요한 프레임워크가 아닙니다. 한 번의 모델 호출이나 도구 몇 개를 순차적으로 사용하는 에이전트라면 일반 SDK나 단순한 agent loop가 더 빠르고 관리하기 쉽습니다.

그래프를 설계하는 비용은 실행 전에 먼저 발생합니다. 매번 같은 순서를 반복하는 업무인지, 실행해봐야 다음 단계가 정해지는 업무인지 먼저 구분하고 LangGraph의 사용을 고민한다면 불필요한 설계 비용을 줄일 수 있습니다.

2. Graph가 복잡해지면 설계 자체가 어려워집니다

Node와 조건이 계속 늘어나면 어떤 상태에서 어떤 경로로 이동하는지 파악하기 어려워집니다. 처음부터 모든 예외 상황을 Graph에 넣기보다 핵심 업무 흐름을 먼저 만들고, 실제 운영에서 필요한 분기와 복구 흐름을 점진적으로 추가하는 것이 좋습니다.

3. State에 무엇을 저장할지 명확하게 정해야 합니다

모든 정보를 State에 넣으면 데이터가 계속 커지고 관리하기 어려워집니다. 현재 작업에 필요한 정보, 장기적으로 기억해야 할 정보, 외부 데이터베이스에서 다시 조회할 수 있는 정보를 구분해야 합니다. 개인정보나 민감한 데이터를 상태에 저장할 때는 보안과 보존 정책도 함께 검토해야 합니다.